Ultimate Blitz Basic 2.1/Ultimate Blitz Basic 2.1 (1997)(Acid Software).iso/blitz2_manual

Text File | 1997-10-13 | 484KB | 13,801 lines

WELCOME

Thank you for purchasing Blitz Basic 2.1 We at Acid Software hope that it
provides you with an environment, that gives you the total freedom you need
to explore your ideas on the Amiga computer.

Blitz Basic 2.1 gives you the power to make commercial quality games such as
Super Skidmarks or BlitzBombers and the flexibility to create applications
such as paint packages and spreadsheets.

WHAT YOU SHOULD HAVE RECEIVED

PROGRAM DISK

This disk is installed with a limited Workbench 1.3 environment so that
floppy disk users can boot straight from this disk. It contains six main
files:

Acidlibs        The standard Blitz2 commands.
Blitz2            The compiler
Deflibs            The additional commands created from third party
            libraries.
Help            The on-line help program.
Help.dat        The data file for the on-line help program.
Ted            The editor.

EXAMPLES DISK

This disk is full of demos and examples written in BlitzBasic 2.1 They
provide a wealth of information for Blitz Basic 2.1 programmers to advance
their skills. The examples have been placed into seven separate directories:

Amigamode:-    Applications related examples on gadgets, windows,
        arexx, etc.
AndrewsDemos:-    Games/graphics related examples by Andrew Blackbourne.
Blitzmode:-    Game/graphics related examples on scrolling, blitting,
        animation, etc.
MarksDemos:-    Applications related examples by Mark Sibly.
SimonsDemos:-    Games related examples by Simon Armstrong.
TedsDemos:-    Demo/graphics related examples by Ted Bailey.
Tools:-        Application and games related tools and source code.

A


EXTRAS DISK

This disk is full of additional utilities and programs for users with more
than 1 Mb of memory and a hard drive. To squeeze as much as possible onto
the disk, the files have been compressed using an 'archiver' called Lha.
The evaluation version of this program is required so that you can unpack
the files. This disk contains five archives:

BigDeflibs.lha:-    All the amigalibs and third party libraries compiled into
            one file.
Blitzlibs.lha:-        All the object code for amigalibs and the third party
            libraries and the Blitz resident files and utilities.
LibsDev.lha:-        An archive for advanced users wanting to create their
            own libraries. It contains documentation, example
            library source code and test example code for the
            third party libraries.
NewDebugger.lha:-    An advanced debugging utility that allows you to
            view copperlists, memory etc.
NewTeditor.lha:-    An Amiga style guide compliant editor that requires
            Workbench 2.0 or greater.

    MANUAL

This manual contains detailed descriptions of all the standard commands
found in Acidlibs. It also contains some helpful examples and hints on how
to get the best performance from Blitz.

REGISTRATION CARD

Please fill out this card and mail it back to your Acid Software
Distribution Centre. Once we have received your card, you will be allocated
a Blitz User number, please quote it in all subsequent communications. You
will not be eligible for any support, bug fixes and updates without
registering yourself as a Blitz Basic 2.1 user.

B


INSTALLING BLITZ

NB: Please make backup copies of all your disks before using Blitz.

Floppy disk users

You can start using Blitz Basic 2.1 straight away. Insert the program disk
and switch on your Amiga. Double-click on the Blitz2 icon and after a short
pause an 'okee dokee' requester will appear. Click on this and you are now
ready to start. Please refer to chapter one 'Getting Started' for
instructions on how to load the examples.

Hard disk users

1.     Create a new directory on your hard disk. Blitz is a good name to
    choose.

2.     Copy the following files from your Blitz Program floppy disk into
    the new directory on your hard disk:
                acidlibs
                Blitz2
                Blitz2.info
                deflibs
                help
                help.dat
                Ted
                Ted.info

3.     Create two new sub-directories in your blitz directory:
                Blitzlibs
                Userlibs

4.     Add the following two assigns to your start-up sequence:

        Assign Blitz2: <hard drive>:<new directory>
        Assign Blitzlibs: <hard drive>:<new directory>/<new
        sub-directory>

        e.g: Assign Blitz2: DH1 :Blitz
        Assign Blitzlibs: DH1 :Blitz/Blitzlibs

5. Restart your Amiga and you are ready to run Blitz from your hard disk

C


INSTALLING THE ADDITIONAL UTILITIES AND EXTRAS

You do not need to install the additional utilities and extras in order to
use Blitz.
You can simply boot from your Blitz Program disk and start writing your
programs.
The extras disk is provided for users with more memory and hard disk drives
and for the more advanced programmers out there.

All the additional files will need to be un-archived before they can be
installed or used. In order to do this you will need the evaluation version
of Lha by Stefan Boberg, which unfortunately wouldn't fit on the disk. It
is available from most Public Domain software suppliers, Aminet and most
magazine coverdisks.

One way to extract the files from the archives once you have the Lha
program, is:

1. Load up Workbench.

2. Copy the Lha program file into your Workbench:C drawer.

3. Open a shell by double-clicking on the shell icon in the system drawer.

4. Type: Lha x
    e.g: Lha x Extras:BigDeflibs.lha Ram:

5. Copy the un-archived file into its correct place
    e.g: copy deflibs DH1 :Blitz

D


What's in the archives and where do the files go?

BigDeflibs.lha:

This contains a single 1 59K deflibs file that is a  direct
replacement  for  the small 55K deflibs file in your Blitz  drawer.   Floppy
disk  users  do not have enough room on their program disk to  install  this
file.

Blitzlibs.lha:

This contains two directories and several resident files and
utilities.   Floppy  disk users should format a blank  disk  and  rename  it
Blitzlibs  and  then un-archive the file onto this disk.   Hard  disk  users
should  un-archive  this file into the Blitzlibs drawer  they  created  when
installing Blitz.

LibsDev.lha:

This contains six directories and a documentation file. Floppy
disk  users  should format a blank disk and un-archive the  file  onto  this
disk.   Hard  disk users should create a new sub-directory  in  their  Blitz
drawer (a good name would be developers)  and then un-archive this file into
the new directory.

NewDebugger.lha:

This   contains   the   new   1   52K  defaultdbug  file,
documentation on its use and an example directory containing test  programs.
The  file  is  a  direct replacement for the small 33K defaultdbug  in  your
Blitz  drawer.   The  examples and documentation can  be  installed  in  any
suitable directory.  Floppy disk users will not be able to install this file
as there is not enough room on their program disk.  NB: The big 159K deflibs
file must be installed to use the advanced debugging utility.

NewEditor.lha:

This  contains the new 57K Ted file and some documentation on its use.   The
file is a direct replacement for the 59K Ted file in your Blitz drawer.  The
documentation can be installed in any suitable directory.  Floppy disk users
will  not  be  able  to  install this file and the additional  libraries  it
requires  as there is not enough room on their program disk.  NB:   The  new
editor requires Workbench 2.0 or greater.

E


Directory Tree for Hard Disk users

DH1:-Blitz ------------------------------------------program files
         |
    |
     --------- Blitzlibs --------------------------- resident files
    |               |
    |           |
    |        |--- amigalibs        amiga libraries
    |         --- otherlibs        third party libraries
    |
     ---- Developers----------------------------- documentation
    |    |
    |    |
    |    |---  acidlibsrc     acid library source code
    |    |---  amigaincludes     system includes
    |    |---  toolsource     developer toolsource code
    |    |---  userlibdocs     does for third party fibs
    |    |---  userlibprogs     test programs for third party fibs
    |     ---  Userlibsource     source code for third party fibs
    |
    |--- Examples
    |    |
    |    |---  amigamode
    |    |---  andrewsdemos
    |    |---  blitzmode
    |    |---  marksdemos        ;example code
    |    |---  simonsdemos
    |    |---  tedsdemos
    |     ---  tools
    |
    |
    |
    |
     --- Userlibs

NB:   The  developers and examples directories are optional.   Blitzlibs  is
mainly required for the resident files that some programs use.  Userlibs  is
only required for testing beta-versions of your own libraries.

F


BUM SUBSCRIPTIONS AND SUPPORT

If you want to receive the latest additions, fixes and example code, you can
subscribe  to  the  Blitz User Magazine currently at issue  eight.   We  are
hoping  to have BUM9 ready shortly after Christmas 1995 and it will  consist
of  two  disks  that will unpack onto four disks (this is the  standard  BUM
format).  For œ10.00,  registered users can have the next two issues of  BUM
delivered to their door.  Please note, existing BUM subscribers have already
paid for the next two issues.

UK and European registered users should contact:

Acid Software
c/o Guildhall Leisure Services
Unit 15, Guildhall Industrial Estate
Kirk Sandall
Doncaster
DN3 1QR

Blitz Installation Support
Tel [phone] Mon - Fri 9Am - 5Pm (** UK ONLY **)

EMail:- [e-mail]

US and Australasian registered users should contact:

Email: [e-mail]

G


PROBLEMS YOU MAY ENCOUNTER


Error Type Explanation and Solution

Can't  compile  the program,  there are    ??????'s  instead of Blitz commands:
The program may be  using  a  Blitz command from the third party libraries.
you got the large deflibs installed in your Blitz drawer ? NB:  Floppy users
cannot  install the large deflibs file as there isn't enough room  on  their
program disk

Can't  load resident :A few programs use resident files which are  contained
in  the  blitzlibs  archive.  Floppy users  have  you  named  a  blank  disk
Blitzlibs un-archived the file blitzlibs.lha onto it? Hard Disk  users  have
you  un-archived the blitzlibs.lha file into the correct drawer on your hard
drive ? Have you added the assign for Blitzlibs: to your startup sequence ?

Please insert volume Blitzlibs:        See above explanation and is your
deflibs file in the same drawer as the Blitz2 program file ?.

Can't  load  graphic/shape/sound/include Blitz can't find  the  file  to  be
loaded. Have you used the Change Directory gadget on the file requester ?

H


CONTENTS

1. GETTING STARTED                    1

Installing Blitz                    1
Registration Card                    1
OkeeDokee?                        1
Running the Examples                    1
Current Directories                    2
Using Ted the Blitz2 Editor                2
Entering Text                        3
Highlighting blocks of text                3
The Editor Menus                    4
The Blitz File Requester                7
The Compiler Menu                    8
Compiler Options                    9
Keyboard Shortcuts                    10

2. BLITZ BASIC'S                    11

My First Program                    11
The Print Command                    11
Formatted Printing                    12
A Simple Variable                    12
Blitz2 Operators                    12
Boolean Operators                    14
Binary Operators                    14
Multiple Commands                    14
A Simple Loop                        14
Nested Loops                        15
While..Wend and Repeat..Until                 15
Endless Loops                        16
Using String Variables                    16
Program Flow                        17
Jumpin' Around                        17
Getting Input from the User                18
Arrays                            19

3. TYPES, ARRAYS AND LISTS                21

Numeric Types                        21
Default Types                        22
The Data Statement                    22
Numeric Overflows                    23
String Types                        23
System Constants                    23
Primitive Types Summary                    23
NewTypes                        24
Arrays inside NewTypes                    25
The UsePath Directive                    26
ARRAYS                            27
LISTS                            28
Dimming Lists                        28
Adding items to a list                    28
Processing Lists                    29
Removing Items From a List                30
List Structure                        30
The Pointer Type                    30

4. PROCEDURES                        31

Introduction                        31
Statements                        31
Functions                        32
Recursion                        33
Accessing Global Variables                33
Procedures Summary                    33
Assembler in Blitz Procedures                34

5. ERROR CHECKING&DEBUGGING                 35

Compile Time Errors                    35
The CERR Directive                    36
Runtime Errors                        36
The Blitz Debugger                    37
The Debugger Gadgets                    38
Tracing program execution                38
Resuming Normal Execution                39
Viewing command history                    39
Direct Mode                        39
Debugger Errors                        40


6. BLITZ OBJECTS                    41

Blitz2 Objects Overview                    41
Object Similarities                    41
Object Maximums                        42
Using an Object                        42
Input/Ouput Objects                    43
Object structures                    43
The Blitz Objects                    44
Screens                            44
Windows                            44
Gadget and Menu lists                    44
Palettes                        44
BitMaps                            45
Shapes                            45
Sprites                            45
Slices                            45
Files                            46
Objects Summary                        46


7. BLITZ MODE                        47

Introduction to Blitz Mode                47
Slice Maoic                        47
Smooth Scrolling                    48
Dual-Playfield                        48
Copper Control                        48
The Blitter                        49
QAmiga Mode                        50
Summary                            52


8. ADVANCED TOPICS                    53

Resident Files                        53
Operating System Calls                    54
Operating System Libraries                54
Accessing OS Structures                    55
Locating Variables & Labels                55
Constants                        56
Conditional Compiling                    57
Macros                            58
Macro Parameters                    59
The '0 Parameter                    60
Recursive Macros                    60
Replacing Functions with Macros             61
The CMake Character                     61
Inline Assembler                     62
GetReg & PutReg                     62
Assembler in Procedures                    63


9. PROGRAMMING & OPTIMIZING

Label and Variable Names                65
Style                            65
Naming related problems                    66
Remarks and Comments                    66
Structured programming                    67
Keeping things modular                    67
Along the way...                    68
Keeping your code readable                68
Optimising Code                        69
Algorithms                        69
Loops                            69
Lookup tables                        70
Using Pointers                        70
Testing Performance                    70
Optimising Games                    71


10. PROGRAM EXAMPLES                    73

Number Guessing                        73
Standalone WorkBench progs                74
A Graphic Example                    75
Using Menus & File Requesters                76
String Gadgets                        77
Prop Gadgets                        78
Database Type Aplication                79
List Processor for Exec                    82
Prime Number Generator                    83
Clipped Blits                        84
Dual Playtield Slice                    85
Double Buffering                    86
Smooth Scrolling                    87

11. THE DISPLAYLIBRARY&AGA                89
Introduction                        89
Initialising                        89
Flags used with InitCopList                90
Colors                            90
SmoothScrolling                        90
DualPlayfield                        91
Sprites                            91
FetchMode                        91
Multiple Displays                    91
Advanced Copper Control                    92
Display Example 1                    93
Display Example 2                    94

COMMAND REFERENCE SECTION

R-1: PROGRAM FLOW                 95
R-2: VARIABLE HANDLING                 101
R-3: INPUTOUTPUT COMMANDS             105
R-4: FILE HANDLING & IFFINFO             109
R-5: NUMERIC&STRING FUNCTIONS             113
R-6:  COMPILER DIRECTIVES            121
R-7:  ASSEMBLER DIRECTIVES            125
R-8:  MEMORY CONTROL                127
R-9:  PROGRAM STARTUP                129
R-10: SLICE COMMANDS                131
R-11: DISPLAY LIBRARY                135
R-12: BLITZMODE IO COMMANDS            140
R-13: BITMAP COMMANDS                144
R-14: 2D DRAWING COMMANDS            146
R-15: ANIMATION SUPPORT                148
R-16: SHAPE HANDLING                149
R-17: BLITTING COMMANDS                153
R-18: SPRITE HANDLING                159
R-19: COLLISION DETECTION            161
R-20: PALETTE COMMANDS                163
R-21: SOUND MUSIC & SPEECH            168
R-22: SCREEN COMMANDS                173
R-23: WINDOW COMMANDS                176
R-24: GADGET COMMANDS                188
R-25: MENU COMMANDS                195
R-26: GADTOOLS COMMANDS                198
R-27: ASL LIBRARY COMMANDS            202
R-28: AREXX CONTROL                203
R-29: BREXX COMMANDS                211
R-30: SERIAL PORT COMMANDS            214


APPENDIX

A-1:    COMPILE TIME ERRORS            217
A-2:    OPERATINGSYSTEM CALLS        227
A-3:    AMIGA HARDWARE REGISTERS    237
A-4:    68000 ASSEMBLY LANGUAGE     247
A-5:    RAWKEY CODES                253


1. GETTING STARTED

Installing Blitz

There  are  two  install  programs included on Diskl  of  the  Blitz  disks,
HDInstall  and  Floppyinstall.  From Workbench click  on  the  one  that  is
applicable.  Those installing onto harddisk will want to make sure they have
at  least  4 megs free in the partition they are installing to while  floppy
users  will be informed by the Floppyinstall program of the number of  blank
disks they will need to unpack all the data onto.

Registration Card

Please  fill out this card and mail it back to Acid Software.  You will  not
be  eligible  for  any  support,  bug fixes and updates without  registering
yourself as a Blitz2 user.  We would also like to here about what  you  want
to use Blitz2 for and any things you think need adding to Blitz2.

OkeeDokee?

Once  you have a working backup of the disks or have installed Blitz 2  onto
your harddisk its time to take your new programming language for a spin:

Double click the Blitz2 icon to run the editor/compiler.  The editor  screen
should appear with a copyright notice (which should NOT be ignored!).  Click
on OkeeDokee and you're up and running.

Running the Examples

Okee  dokee,  if you have got this far without any problems you're ready  to
drive  the  speed machine (thats the Blitz 2 editor/compiler  we're  talking
about).

Select  the  LOAD  menu  item,   insert the  examples  disk  or  select  the
Blitz2:Examples  drawer on your harddisk and load in one  of  the  examples.
Any  file  ending with the suffix .bb2 is a source file able  to  be  loaded
into  the Blitz2 editor/compiler.  Once you have loaded a .bb2 file  have  a
read,   guess  what it's going to do then select compile and  run  from  the
compiler menu.

The  only  problem you should have with running the examples is to  do  with
'Current Directories'.

Page 1

Current Directories
If  you changed the pathname in the file-requester to locate the example you
loaded  you will usually need to click on the CD gadget before selecting  OK
on  the  file- requester.  This changes the current directory to that  which
you loaded the example.

By  changing the current directory.  any files the program attempts  to  use
will  be  loaded from the same directory as that from which the source  code
was loaded.

This  means that when the program is executed (run)  and attempts  t`'  load
any  data  or graphics from disk,  the default path (directory it looks  for
files)  will be set to,  the same directory as where the program itself  was
loaded

If  the example comes up with a runtime error "Couldn't Load Shape"  or  the
like  it  will be because the current directory has not been  to  set.   Hit
Escape to exit the debugger and return to the editor.

  If  the  example  crashes the machine,  it its  because  the  same  error
occurred but error checking was disabled on the compiler options menu.

Using Ted the Blitz2 Editor

To enter and compile your programs you need an editor.  Blitz2 comes with  a
text  editor that acts both as an interface to the Blitz2 compiler  as  well
as  a  standalone  ascii editor (ascii is the computer standard  for  normal
text)

The  horizontal and vertical bars are called 'scroll bars'.  when  the  file
you  are  editing is longer or wider than the screen you can  position  your
view  of  the file by dragging these bars inside their boxes with  the  left
mouse button.

At  the  bottom  of  the screen is information about the cursor  position  r
elative  to  the  start of the file you are editing  as  well  as  a  memory
monitor  that  lets you know the largest block of memory available  in  your
Amiga system.

Using the left mouse button you can drag the Blitz2 screen up and down  just
like  any other Amiga screen as well as place it to the back with the  front
to back gadgets at the top right of the screen.



Entering Text

The  editor can be treated just like a standard typewriter,  just  go  ahead
and type, using the return key to start a new line.

The  small  box  that  moves across the screen as you  type  is  called  the
cursor.   Where the cursor is positioned on the screen is where the  letters
will appear when you type.

By  using  the  arrow  keys you can move the cursor  around  your  document,
herein to be known as the file.

If  you  place the cursor in the middle of text you have already  typed  you
can  insert letters just by typing,  the editor will move all the characters
under  and  to  the  right of the cursor along one and insert  the  key  you
pressed into the space created.

The DEL key will remove the character directly under the cursor and move the
remaining text on the line left one character to cover up the gap.

The  key to the left of the DEL key will also remove a character but  unlike
the  DEL  key it removes the character to the left of the cursor moving  the
cursor and the rest of the line to the left.

The TAB key works similar to a typewriter moving the cursor and any text  to
the right of the cursor right by so many columns.

The  RETURN key as mentioned allows you to start a new line.  If you are  in
the  middle of a line of text and want to move all text to the right of  the
cursor  down to a new line use shift RETURN,  this is known as  inserting  a
carriage return.

To join two lines of text use the Amiga keyboard combination.

Using  the  shift keys in combination with the arrow keys you can  move  the
cursor  to the very start or end of a line and up and down a whole  page  of
the document.

By  pointing  with the mouse to a position on the screen you  can  move  the
cursor there by clicking the left mouse button.

See  keyboard shortcuts at the end of this chapter for other important  keys
used with the Blitz2 editor.

Highlighting blocks of text

When editing text,  especially programs you often need to operate on a block
of text.  Position the mouse at the start or end of the block, hold down the
left  mouse  button and drag the mouse to highlight the  area  you  wish  to
copy,  delete,  save or indent. While holding down the button you can scroll
the display by moving the pointer to the very top or bottom of the display.

You  can also select a block with the keyboard,  position the cursor at  the
start of the block of text,  hit the Fl key then position the cursor at  the
end of the text and hit F2.

Page 3

A  special  feature   for   structured   programmers   is  the  Amiga-A  key
combination,  this automatically highlights the current line and  any  above
or below that are indented the same number of spaces.

The Editor Menus

Using  the  right mouse button you can access the menu system of the  Blitz2
editor.  The following is a list of the features accessible from these menus
in order from left to right.

The PROJECT Menu

NEW

Kills the file you are editing from the Amiga's memory.  If the file has
been  changed since it was last saved to disk a requester will  ask  you  if
you really wish to NEW the file.

LOAD

Reads a file from disk.  A file requester appears when you select LOAD which
enables you to easily select the file you wish to edit.  See later  in  this
chapter for a full description of using the file requester.

SAVE

Writes  your  file to disk.  A file requester appears when you  select  SAVE
which enables you to easily select the file name you wish to save your  file
as.   See  later in this chapter for a full description of  using  the  file
requester.

DEFAULTS

Changes the look of the Blitz2 editor.  You can edit the palette, select the
size  of font and tell the system if you wish icons to be created when  your
files  are saved.  The scroll margins dictate how far from the edge  of  the
screen your cursor needs to be before Blitz scrolls the text.

ABOUT        Displays version number and credits concerning Blitz2.



PRINT

Sends your file to an output device usually PRT: the printer device.

CLI

Launches a command line interface from the editor, use the
ENDCLI command to close this CLI and return to the Blitz2 editor.

CLOSEWB

Closes WorkBench if it is currently open.  This option should only  be  used
if  you are running very short on memory as closing WorkBench can free about
40K of valuable ChipMem.

QUIT

Close the Blitz2 editor and returns you to workbench or CLI.

Page 4


The EDITMenu

COPY

Copies  a  block  of text that is highlighted with the mouse  or  fl-f2  key
combination to the current cursor position.  The F4 key is another  keyboard
shortcut for COPY. KILL

Deletes  a  highlighted block of text (same as shift F3  key).   BLOCKTODISK
Saves a highlighted block of text to disk in ascii format.

INSERTFROMDISK

Loads a file from disk and inserts it into the file you are editing  at  the
current cursor position.

FORGET

De-selects a block of text that is selected (highlighted). INSERTLINE

Breaks the line into two lines at the current cursor position. DELETE LINE

Deletes the line of text the cursor is currently located on.

DELETE RIGHT

Deletes all text on the line to the right of the cursor. JOIN

Places the text on the line below the cursor at the end of the current line.

BLOCK TAB    Shifts all highlighted text to the right by one tab margin.

BLOCK UNTAB    Shifts all highlighted text to the left by one tab margin.

The SOURCE Menu

TOP        Moves the cursor to the top of the file

BOTTOM        Moves the cursor to the last line of the file.

GOTO LINE    Moves the cursor to the line number of your choice.

Page 5


The SEARCH Menu

FIND    Will search the file for a string of characters.

NEXT    Positions the curosr at the next occurrence of the Find-String
    entered using the FIND menu option (as below).

PREVIOUS

Will position the curosr at the last occurrence of the Find:  String entered
using the FIND menu option (as below).

REPLACE        Will carry out the same function as discussed in the FIND
        requester below.

After selecting FIND in the SEARCH menu the following requester will appear:
Type  the string that you wish to search for into the top string gadget  and
click on NEXT.  This will position the cursor at the next occurrence of  the
string, if there is no such string the screen will flash.

Use the PREVIOUS icon to search backwards from the current cursor position.

The  CASE SENSITIVE option will only find strings that have the same letters
capitalized,   default is that the search will ignore  whether  letters  are
caps or not.

To  replace the find string with an alternate string click on the  box  next
to REPLACE:  and type the alternate string. REPLACE will search for the next
occurrence of the Find:  string,  delete it,  and insert the Replace: string
in it's place.

REPLACE  ALL  will  carry  on  through   the  file  doing  replaces  on  all
occurrences of the Find: string.

Page 6


The Blitz File Requester

When you select load or save,  Blitz2 places a file requester on the screen.
With the file requester you can quickly and easily find the file on a disk.

Clicking  on  the  top  left of the window or on the CANCEL  gadget  at  the
bottom right will cancel the file requester returning you to the editor.

The  slider at the right enables you to scroll up and down through the files
in the currently selected directory (drawer).

Double  clicking on a file name (pointing to the name and pressing the  left
mouse button twice) will select that file name.

Clicking  on  a  <DIR>  will change to that directory  and  list  the  files
contained in it.

Clicking on PARENT will return you to the parent directory.

Clicking on drives adds a list of all drives,  volumes and assigned  devices
to the top of the file list so you can move into their directories.

You can also enter path and file names with the keyboard by clicking on  the
boxes next to PATH:  and FILE: and entering the suitable text. Then Click on
the OK gadget.

CD  is  a  special  command used when programming in Blitz2  to  change  the
editors  current directory to that specified in the path name.   This  means
that  when  you  select  CLI  or launch a task  from  the  editor  its  root
directory will be that selected by the CD gadget.

The  last  feature of the Blitz2 FileRequester is the ability  to  size  its
window,   h  dragging the bottom right of the window  with  the  left  mouse
button you can see m more files at one time.

Page 7


The Compiler Menu

The  following  is a discussion of the extra options and commands  available
with  Ted  when used in Blitz2 programming mode.  The Compiler menu includes
all the commands needed to control the Blitz2 compiler.

COMPILE/RUN     Compiles your Blitz2 program to memory and if there are no
        errors run the program.

RUN        Runs the program if it has already been successfully
        compiled to memory.

CREATE FILE     Compile your Blitz2 program to disk as an executable
        program.

OPTIONS     See next page for details about Blitz2 compiler options.

CREATERESIDENT

Will  create a 'resident file' from the current file.  A resident is a  file
including  all  constants   and   macro   definitions  as  well  as  newtype
definitions.  By removing large chunks of these definitions from  your  code
and creating a resident (pre- compiled)  file a dramatic increase in compile
speed can be attained.

VIEW TYPE

Allows you to view all currently resident types.  Click on the type name and
its  definition will be shown.  Subtypes can be viewed from  this  expansion
also.

CLI ARGUMENT

Enables  you to pass parameters to your program when executing it  from  the
Blitz2 editor environment just as if you had run the program from the CLI.

CALCULATOR

Allows you do to calculations in base 2,  10 and 16. Precede hex values with
$ and binary with %. It also supports multi levels of parenthesis.

RELOAD ALL LIBS

Will  read  all  files  from  BLITZLIBS:   back  into  the  Blitz2  compiler
environment.  This is useful when writing your own Blitz2 libraries and wish
to test them without having to re-run Blitz2.


Page 8


Compiler Options

The  following  is  a  discussion  of the Options  requester  found  in  the
Compiler menu.

Create Icons for Executable Files:  if on,  the compiler creates an icon  to
accompany  the  file created with the CREATE FTLE option.   This  means  the
program  will be accessible from the WorkBench.  Note:  for the  program  to
execute  correctly when run from workbench the WBStartUp command  should  be
included at the top of the source code.

Enable Runtime Errors:when on will trap runtime errors and invoke the Blitz2
debugger.   See  Chapter 5 for a thorough discussion of  runtime  errors  in
Blitz2.

Make Smallest Code:  selects two pass compile mode,  which always calculates
the minimum amount of memory required for the object code.  Make Smallest is
automatically selected when creating executable files.  Unselected, programs
will compile quicker.

Debug Info:  creates a symbols table during CREATE FILE so executable can be
debugged more easily with debuggers such as Metadigm's excellent MetaScope.

Buffer Sizes:  allows different buffers to be altered when using Blitz2 as a
one  pass  compiler.  These buffers are automatically optimized  when  using
MakeSmallest  (two pass compile).  The one exception is  the  string  buffer
setting,   if  using large strings (such as reading entire  files  into  one
string)  the string workspace buffer should be increased in size  to  handle
the largest string used.

Object Maximums:  allows setting of maximum number of Blitz2 objects such as
screens,   shapes etc.  See Chapter 6 for a thorough explanation  of  Blitz2
objects and their maximum settings.

Resident:  adds precompiled resident files to the Blitz2 environment.  Click
in the box and type in the resident file name.

Page 9


Keyboard Shortcuts

Having to reach for the mouse to execute some of the editor commands can  be
a  nuisance.  The following is a list of keyboard shortcuts that execute the
same options that are available in the menus.

The  right  Amiga key is just to the right of the space bar  and  should  be
used  like the shift key in combination with the stated keys to execute  the
following commands:

Amiga  A  SELECTs all text that is indented the same amount as  the  current
line (strictly for structured programming housekeeping)

Amiga B BOTTOM will position cursor on last line of file

Amiga  D  DELETE  LINE  removes the line of text  on  which  the  cursor  is
currently positioned

Amiga F FIND/REPLACE executes the FIND command in the SEARCH menu

Amiga G GOTO LINE moves cursor to specific line of file

Amiga I INSERT LINE moves all text at and below the cursor down one line

Amiga J JOIN LINE adjoins next line with current line

Amiga L LOAD reads a file from disk

Amiga N NEXT searches for the next occurrence of the 'find string'

Amiga P PREVIOUS searched for previous occurrence of the 'find string'

Amiga Q QUIT will exit the Blitz2 editor

Amiga  R REPLACE will replace text at cursor (if same as find string)   with
the alternate string specified with the Find command.

Amiga S SAVE writes a file to disk

Amiga T TOP moves the cursor to the top of the file

Amiga W FORGET will unhighlight a selected block of text

Amiga Y DELETE TO RIGHT of cursor

Amiga Z CLI

Amiga  ? DEFAULTS allows the user to change the look and feel of the  Blitz2
editor

Amiga ] BLOCK TAB moves whole block right one tab

Amiga [ BLOCK UNTAB moves whole block left one tab

Page 10


2. BLITZ BASIC'S

My First Program

Type in the following two lines:

Print "This is my first program written in Blitz2!"
MouseWait
End

Then using the right button select COMPILE&RUN from the top right menu.

If  you  have typed the program in correctly a Blitz2 CLI Window will appear
with the message,  click the mouse button to return to the editor Thats  all
there is to it!

The Print Command

Position  the  cursor on the Print statement and press the  HELP  key,   the
syntax  for the Print command appears at the top of the screen.   It  should
read:

Print Expression[,Expression...]

The  square brackets mean that the Print command will accept any  number  of
expressions  separated by commas.  An expression can be any number,   string
(text  in  "quotes"),  variable or BASIC calculation.  The following  is  an
example of all these.

Don't forget to include the MouseWait command when you test this,  otherwise
Blitz2  will print the message and return you to the editor before you  even
have time to read it.

    Print 3,"CARS",a,a*7+3

The following should be printed out on the CLI window:

    3CARS03

If we add some spacing between each expression like so:

    Print 3," CARS ",a," ",a*7+3

The result will be the line:

    3 CARS O 3

Page 11


Formatted Printing

We  can change the way Blitz2 prints numbers using the Format command,  this
is useful if want to print a list of numbers, in a column.

The  NPrint  command is used to move the cursor to a newline after  printing
the expressions.

Format "###.00"
Nprint 23.5
Nprint 10
Nprint .5
Nprint 0
MouseWait

A Simple Variable

The  main power of a programming language lies in it's ability to manipulate
numbers and text. Variables are used to store these pieces of information.

The following line will store the value 5 in the variable a:

    a=5

The variable a now holds the value 5.  We can tell the computer to add I  to
the value of a making it 6 using the following expression:

    a=a+1

An expression can contain more than one operation,  brackets can be used  to
make one operation be evaluated before the others:

    a=(a+3)*7

Blitz2 Operators

An evaluation is a collection of variables, constants, functions and operators.
Examples of operators are the plus and minus signs.

An  operator  will  generate an outcome using either the  variable  on  it's
right:

    a=NOT 5

or from the variables on it's left and right:

    a=5+2

An evaluation can include multiple operators:

    a=5*6+3

Page 12


As  in  mathematics the order the operators are evaluated  will  affect  the
outcome,  if the multiply is done first in the above example the  result  is
33, if the addition was done first, 5*(6+3), the result will be 40.

When  Blitz  performs  an  evaluation some operators  have  precedence  over
others and will be evaluated first,  the following two evaluations will have
the  same  result because Blitz2 will always evaluate multiplication  before
addition:

    a=5*6+3 is the same as a=3+5*6

To override the order which Blitz2 evaluates the above,  parenthesis can  be
added, operations enclosed in parenthesis will be evaluated first:

    a=5*(6+3)

The  following table lists the Blitz2 operators grouped in order of priority
(LHS=lett hand side,  RHS=right hand side).  Operators in the same box  have
the same priority.

NOT            RHS logically NOTted
            RHS arithmetically negated

BITSET        LHS with RHS bit set
BITCLR        LHS with RHS bit cleared
BITCHG        LHS with RHS bit changed
BITTST        true if LHS bit of RHS is set

/\            LHS to the power of RHS

LSL            LHS logically shifted left RHS times
ASL            LHS arithmetically shifted left RHS times
LSR            LHS logically shifted right RHS times
ASR            LHS arithmetically shifted right RHS times

&            LHS logically ANDed with RHS
|            LHS logically ORed with RHS

*            LHS multiplied by RHS
/            LHS divided by RHS

+            LHS added to RHS
-            RHS subtracted from LHS

=            true if LHS is equal to RHS
<>            true if LHS is not equal to RHS
<            true if LHS is less than RHS
>            true if LHS is greater than RHS
<=            true if LHS is less than or equal to RHS
>=            true if LHS is greater than or equal to RHS

AND            LHS logically ANDed with RHS
OR            LHS logically ORed with RHS

Page 13


Boolean Operators

The  boolean system can only operate with two values,  true and  false.   In
Blitz2  false is represented by the value (),  true with the value -1.   The
operators =,  <>,  <=,  =>,  > and < all generate a boolean result (true  or
false).

NPrint  2=2 will print the value - I as the result of the operation  2=2  is
true.   The  operators  OR,  AND and NOT can be used as  boolean  operators,
Nprint  2=2 AND 5=6 will print ()  as the result is false.  The OR  operator
will return true if either the left or the right hand side is true.  The NOT
operator  returns false if the following operand is true  and  true  if  the
operand is false.

Binary Operators

Many  of  the  Blitz2  operators  perform  binary  type  arithmetic.   These
operations  are very fast as they directly correspond to instructions  built
into the computer's microprocessor.

The binary system means that all numbers are represented by a series of I  s
and 0s. A byte is made up of X such bits, a word 16 and a long word 32.

Further  discussion of the binary operators in Blitz2 can be  tound  in  any
text covering the 68000 microprocessor.

Multiple Commands

The  following program starts a with a value of 0,  it then proceeds to  add
12 to the value of a and print the result 4 times.

    a=0
    a=a+12:Nprint a
    a=a+12:Nprint a
    a=a+12:Nprint a
    a=a+12:Nprint a
    MouseWait

Note how we can put two commands on the same line by separating each command
with a colon character.  Also, the first line a=0 is not needed as variables
in Blitz2 always start out with a value of 0 anyway.

A Simple Loop

The  following program prints out the 12 times table.  Instead of typing  in
12 lines to do this we use a For..Next loop.  A loop is where the program is
told to repeat a section of program many times.

For  i=1 To 12..Next will execute the commands between the For and  Next  12
times, the variable i is used to keep count.

The asterisk * means multiply,  a=i*12 means the variable a now equals 12  x
the

Page 14


variable i. Because i is counting up from 1 to 12 the variable a is assigned the values 12, 24, 36,4X.. as the program loops.

    For i=1 To 12
        a=i*1 2
        NPrint i,"*",12,"=",a
    Next
    MouseWait
    End

Note  how  the 2 lines inside the loop are indented across the  page.   This
practice  makes  it easy to see which bits of the program are  inside  loops
and which are not.

The  Tab  key can be used to move the cursor across the page so many  spaces
when typing in lines that are indented.

Now  try  changing the first line to For i=l To 100,  as  you  can  see  the
computer has no problem what so ever doing it's 12 times table!

We  could also change the number 12 in the first 3 lines to any other number
to generate an alternative times table.

Nested Loops

The following program is an example of nesting loops,  a term that refers to
having  loops  inside of loops.  By indenting the code that  is  inside  the
inner  loop even further we can keep a check to make sure each For statement
lines up with each Next statement.

    For y=1 To 12
        For x=1 To 12
            NPrint y,"*",x,"=",x*y
        Next
    Next
    MouseWait

The  nesting  of the For x=1 To 12 inside the For y=1 To 12 means  the  line
inside  the  For x will be executed 12 x 12 times,  each  time  with  a  new
combination of x and y.

While..Wend and Repeat..Until

There  are  two  other simple ways to program loops in Blitz2 besides  using
For..Next.

While..Wend and Repeat..Until loops are used as follows:


    While a<20
        Nprint a
        a=a+1
    Wend

Page 15


    Repeat
        Nprint a
        a=a+1
    Until a>=20

As  with a lot of BASIC commands they are pretty much self explanatory,  the
inside  of a While..Wend will be repeated while the condition remains  true.
a Repeat..Until will loop until the condition is true.

A  condition can be any evaluation such as While a+l0<SO,  While f=0,  While
b<>x*2 and so on.

The difference between the two loops above is that if a was greater than  20
to  start  with,  the Repeat..Until would still execute the code inside  the
loop once, where as the While..Wend would not.

Endless Loops

When  a program gets into the situation of repeating a loop for ever  it  is
called  an endless loop.  In this situation the programmer must be  able  to
override the program and tell it to stop.

To  interrupt  a  program the Ctrl/Alt C keyboard  sequence  must  be  used.
Holding down the Ctrl key and the LeftAlt key press C,  this will  stop  the
program and the debugger screen will appear.  To exit from the debugger  and
return  to  the  editor  use the Esc key (top left of  the  keyboard).   The
debugger is covered in detail in Chapter 5.

Using String Variables

Variables that contain text not numbers are called string variables.  String
variables  require  the $ signs after their names.  The  following  shows  a
simple example of a string variable:

    a$="Simon"
    Nprint a$
    MouseWait

Similar  to  numeric  variables the = sign is  used  to  assign  the  string
variable  a  value.   The  +  sign  can be  used  to  add  strings  together
(concatenate):

    a$="Simon ": b$="Armstrong" :c$=a$+b$

The  variable  c$  will  now  contain  the string  "SimonArmstrong".   Other
functions that manipulate strings are detailed in the reference  section  of
this manual.

Page 16


Program Flow

Often a program will have to decide to do either one thing or another,  this
is  called prograzn flow.  The If Then commands are used to tell the program
to  do  something only If some condition is true.  The following  will  only
print "Hello" if the variable a has the value 5:

    If a=5 Then Print "Hello"

The  above line could be changed to do a section of commands if a was  equal
to 5 using the IF..Endif structure:

    If a=5
        Print "Hello"
        a=a-1
    Endif

The  Else command is used to execute an alternative section if the condition
is not true:

    If a=5
        Print "Hello"
    Else
        Print "GoodBye"
    Endif

Note  how  we indent code inside conditional blocks just like  we  did  with
loops.  This makes the code more readable,  it is easier to see which  lines
of code will be executed when the condition is true etc.

The  condition  after  the  If command can be any complex  expression,   the
following are some examples of possible test conditions:

    If a=1 OR b=2
    If a>b+5
    If (a+10)*50 <> b/7-3

An  appendix  at  the end of this manual contains a complete description  of
using multiple operators and their precedence.

Jumpin' Around

Often the program will need to jump to a different section of the code.  The
Goto and Gosub routines are used for this.  The location that the program is
jumping  to needs a label so that Goto and Gosub can reference the  location
they are jumping to. The following uses the label start:

    Goto start
    NPrint "HI THERE"
    start
    MouseWait

Page 17


Because  the Goto statement makes the program jump to the label start,   "Hi
There" is never printed.

The Gosub comn1and is used to jump to a subroutine,  a subroutine is a piece
of code terminated with a Return statement.  This means that after executing
the  subroutine,  the program flow returns to where the  Gosub  command  was
executed and carries on.

    .start:
        Gosub message
        Gosub message
        Gosub message
        MouseWait
        End

    .message
        NPrint "Hello"
        Return

Note  how  the  labels are preceded with a period This makes  them  mousable
labels  which  appear in a list on the right of the editor screen.   We  can
make  the  cursor  jump to a label by clicking it in  this  list.   This  is
extremely useful for finding your way around when editing large programs.

Getting Input from the User

A  program will often require input from the user when it is running  either
via  the keyboard or mouse.  For instance,  the MouseWait command will  stop
the program until the user clicks the left mouse button.

Keyboard input can be obtained using the Edit and Edit$ functions  which  is
the same as the Input command in other languages.

The  following asks the user for their name,  and places what they type into
a string variable:

    Print "What is your name?"
    a$=Edit$(80)
    NPrint "Hello ",a$
    MouseWait

The  number 80 in Edit$(80)  refers to the maximum number of characters  the
user can type.

To  input numbers from the user the Edit function is used,  a=Edit(80)  will
let  the user type in any number up to 80 digits long and will place  it  in
the variable a.

Page 18


Arrays

Often  a  program will need to manipulate groups of numbers or strings.   An
array  is  able  to  hold such groups.  If we needed to keep  track  of  ten
numbers that were all related,  instead of using ten different variables  we
can define an array to hold them.

The Dim statement is used to define an array:

    Dim a(10)

The  variable a can now hold 10 (actually 11)  numbers,  to access  them  we
place an index number inside brackets after the variable name:

    a(1 )=5
    a(2)=6
    a(9)=22
    NPrint a(9)
    a(1)=a(1)+a(2)
    NPrint a(1)

The  power of an array is that the index number can be a variable,   if  i=2
then a(i) refers to the same variable ,IS a(2).

The  following  inputs  5  strings fron1 the user using  a  For..Next  loop,
because the strings are placed in an an-ay they can be printed back out:

    Dim a$(20)

    NPrint "Type in 5 names"
    Fori=1 To5
        a$ ( i) = Ed it$ (80)
    Next

    NPrint "The names you typed were"
    For i=1 To 5
        NPrint a$(i)
    Next

    MouseWait Next


Page 19


3. TYPES, ARRAYS AND LISTS

Numeric Types

Blitz2  supports 6 different types of variables There are  5  numeric  types
for  storing numeric values with differing ranges and accuracies as well  as
a string type used to store strings of characters (text)

The  following  table  describes  each Blitz2  numeric  variable  type  with
details on its range and accuracy and how many bytes of memory each requires

Type    Suffix         Range        Accuracy        Bytes

Byte      .b          +-129         integer          1

Word      .w          +//-32768     integer                2

Long      .l              +/-2147483648  integer                4

Quick      .q              +/-32768.0000  1/65536                  2

Float      .f             +/-9*10/\18    1/10/\18                 4

The Quick type is a fixed point type,  less accurate than floating point but
faster.

The  Float  type  is the Floating Point type supported  by  the  Amiga  last
Floating Point libraries.

A  variable is assigned a certain type by adding the relevant suffix to it's
name After the first reference to a variable,  its type is assigned and  any
future references do not require the suffix unless it is a string variable.

The  following  are  some examples of typical numeric variables  with  their
relevant sutfix.

    mychar b=127
    my_score.w=32000
    chip.l=$dffOOO        ;$ denotes a hex value
    speed3.q=500/7        ;a quick has 3 d.p. accuracy
    light_speed.f=3e8    ;e is exponent i.e. 3X10A8


Page 21



Default Types

If  no  suffix  is used in the first reference of a variable,   Blitz2  will
assign  that  variable with the default type.  This is initially  the  Quick
type.

There  are two forms of the DefType command,  one which changes the  default
type  the  other which defines the type of a list of variables supplied  but
which does not affect the default type.

The following code illustrates both uses of DEFTYPE:

    a=20             ;a will be a quick
    DEFTYPE .f         ;vars without suffix will now default to float
    b=20             ;b will be a float
    DEFTYPE .w c,d     ;c & d are words, default still float

Note:  the second instance of DEFTYPE should be read define type rather than
its  first use which stands for change default type.  The default  type  can
also be set to a newtype (see following section).

Other  Blitz2  structures  that  work with  a  certain  type  such  as  data
statements,  functions,  peeks and pokes will also all use the default  type
if no type suffix is included.

The Data Statement

The  Data  statement is used-to hold a list of values that can be read  into
variables.   The  Restore command is used to point the  data  pointer  at  a
certain Data statement.

A.type suffix is added to the data statement to define what type the  values
listed are.

The following is an example of using Data in Blitz2:

    main:
        Read a,b,c
        Restore myfloats
        Read d.f
        Restore mystrings
        Read e$,f$,g$
    myquicks:
        Data 20,30,40
    myfloats:
        Data.f 20.345,10.7,90.111
    mystrings:
        Data$ "Hello","There","Simon"
Note:  if the data pointer is pointing to a different type than the variable
listed in the Read statement a Mismatched Types runume error occurs.

Page 22


Numeric Overflow & Unsigned Integers

When  a variable is assigned a value outside of it's range (too large),   an
overflow error will occur.  The following code will cause an overflow  error
when it is executed:

    a.w=32767     ;a is a word containing the number 32767
    a=a+1        ;ovefflow occurs as result is out of range

Overflow  checking is optional and can be enabled/ disabled in  the  RunTime
errors  options of the Compiler Configuration.  The default setting  is  off
meaning  the  above  code  will  not generate  a  runtime  error.   In  some
instances,   the  integer  types  will be  required  to  represent  unsigned
(positive only)  numbers.  For example,  a byte variable will be required to
hold  values  between O and 255 rather than -127 to 128.  Overflow  checking
has  to  be disabled in the Error Checking requester of the Compiler Options
window to use unsigned ranges such as this.

String Types

A  string  is  a  variable  that is used to store a  string  of  characters,
usually  text.   The suffix for a string variable is  either  a  .s  or  the
traditional $ character.

Unlike  numeric variables the suffix must always be included with the  name.
Also, string variable names MAY be re-used as numeric variable names.

The following is quite legal:

    a$="HELLO"
    a.w=20
    NPrint a,a$

System Constants

Blitz2  reserves a few variables that hold special values  known  as  system
constants.   The  following variables are reserved and  contain  the  listed
values:

    Pi         =    3.1415
    0n         =    -1
    0ff        =     0
    True     =     -1
    False     =    0

Primitive Types Summary

Blitz2 currently supports 6 primitive types.  Byte, Word and Long are signed
8,  16 and 32 hit variable types. The Quick type is a fixed point type, less
accurate  than floating point but t:aster.  The Float type is  the  Floating
Point type supported by the Amiga Fast Floating Point libraries.

The  String  type  is  a standard BASIC implementation of  string'  variable
handling.

Page 23


Using  the  DetType directive.  variables can be defined  as  certain  types
without adding the relevant suffix.  Once a variable is defined as a certain
type  the  suffix  is not necessary except in the case of  string  variables
when the suffix must always be included.

A  variable  can only be of one type throughout the program  and  cannot  be
defined  as any other except again in the case of strings where the variable
name can ALSO be used for a numeric type.

NewTypes

In  addition to the 6 primitive types available in Blitz2,  programmers also
have available the facility to create their own custom types.

A NewType is a collection of fields,  similar to a record in a database or a
C  structure.  This enables the programmer to group together relevant fields
in one variable type.

The following code shows how fields holding a person's name,  age and height
can be assigned to one variable:

    NEWTYPE .Person
        name$
        age.b
        height.q
    End NEWTYPE

    a.Person\name= "Harry",20,2.1

    NPrint a\height

Once  a NewType is defined,  variables are assigned the new type by using  a
suffix of .NewTypename for example a.Person

Individual  fields within a NewType variable are accessed and assigned  with
the backslash character "\" for example: a\height=a\height+1.

When  defining a NewType structure,  field names without a  suffix  will  be
assigned the type of the previous field.  More than one field can be  listed
per line of a NewType definition,  they must however be separated by colons.
The following is another example of a NewType definition:

    NewType .nme
        x.w:y:z    ;y & z are also words (see above)
        value.w
        speed.q
        name$
    End NewType

References to string fields when using NewTypes do',at require the $  or  .s
suffix  as  normal string variables do,  including the suffix will  cause  a
Garbage at End of Line compile time error.

Page 24


From the first example:

    a\name="Jimi Hendrix"     ;this is cool
    a\name$="Bob Dylan"     ;this is uncool!

Previously  defined  NewTypes   can   be   used  within  subsequent  NewType
definitions.  The following is an example of a NewType which itself includes
another NewType:

    NewType .vector
        x.q
        Yq
        z.q
    End NewType

    NewType .object
        position.vector
        speed.vector
        acceleration.vector
    End NewType

    DefType .object myship ;see following paragraph!

    myship\position\x=1OO,O,O

Note  how we now need to use two backslashes to access the fields in  myship
just like a pathname in DOS.

A NewType,  once defined,  can be used in combination with both forms of the
DetType command just as though it was a another primitive type.

Arrays inside NewTypes

Besides including primitives and other newtypes within newtypes,  it is also
possible to include arrays inside NewTypes The square brackets  [  &  ]  are
used when defining arrays inside newtypes.

Unlike  normal arrays,  arrays in newtypes are limited to a single dimension
and  their  size must be dimensioned by a constant not a variable.   However
the array may be of any type including newtypes.

Also  unlike arrays.  the dimension size between the square brackets is  the
size of the array so addess.s[4] allocates 4 strings indexed 0..3.

The following is an example of using an array inside a newtype:

    NEWTYPE .record
        name$
        age.w
        address.s[4] ,same as address$[4]
    End NEWTYPE

Page 25


    DEFTYPE .record p

    p\address[0]="10 St Kevins Arcade"
    p\address[1]="Karangahape Road"
    p\address[2]="Auckland"
    p\address[3]="New Zealand"

    For i=0 To 3
        NPrint p\address[i]
    Next

    MouseWait

The  [index] can be omitted in which case the first item (item 0)   will  be
used.

Defining an array inside a newtype with 0 elements creates a union with  the
following field (both fields occupy the same memory in the NewType).

The UsePath Directive

Often when using complex NewTypes,  pathnames to access fields within fields
can become very long.

Often  a  routine wil1 be dealing only with one particular  field  within  a
newtype. By using the UsePath directive large pathnames can be avoided.

When  a  backslash precedes a variable or field name Blitz2 will insert  the
UsePath path definition when it compiles the program.

The following code:

    UsePath shapes(i)\pos
    For i=0 To 9
        \x+1 0
        \y+20
        \z-10
    Next

is expanded internally by the compiler to read:

    For i=0 To 9
        shapes(i)\pos\x+1 0
        shapes(i)\pos\y+20
        shapes(i)\pos\z-1 0
    Next

The UsePath directive can help to make routines a lot more readable and  can
save a lot of typing!

Note  that UsePath is a compiler directive,  this means that it affects  the
compiler  as  it reads through your program top to bottom not the  processor
when it runs your

Page 26


program.

This  means  that if a routine jumps to somewhere else in  the  program  the
UsePath  in effect will be governed by the closest previous usepath  in  the
listing.

ARRAYS

Arrays  in  Blitz2  follow normal BASIC conventions.   All  Arrays  MUST  be
dimensioned before use,  may be of any type (primitive or NewType)  and  may
be any number of dimensions.

All  arrays are indexed from 0..n where n is the size.  As with most BASIC's
an  array  such  as  a(50)   can actually hold  51  elements  indexed  0..50
inclusive.

As  with all variable definitions an array will be of default type unless  a
.type suffix is added to the array name:

    Dim a.w(50)    fan array of words

The  ability to use arrays of NewTypes often reduces the number of arrays  a
BASIC program requires.

The following:

    Dim Alienflags(1OO),Alienx(1OO),Alieny(100)

can be implemented with the following code:

    NEWTYPE .Alien
        flags.w
        x.w
        y.w
    End NEWTYPE

    Dim Aliens.Alien(100)

You may now access all of the required alien data using just one array.
To set up all of the aliens x and y entries with random coordinates

    For k=1 To 100
        Aliens(k)\x=Rnd(320),Rnd(200)
    Next

This  also makes it much easier to expand the amount of information for  the
aliens  simply  by  adding more entries to the NewType definition,   no  new
arrays are required.

Note:  unlike most compilers,  Blitz2 DOES allow the dimensioning of  arrays
with a variable number of elements for example:  Dim a(n).  Also strings  in
arrays  do  not  require a maximum length setting as is the case  with  some
other languages.

Page 27


LISTS

Blitz2 also supports an advanced form of the array known as the List.  Lists
are arrays, but with slightly different characteristics.

Often  only  a  portion of the elements in an array will  be  used  and  the
programmer  will  keep a count in a separate variable of how  many  elements
are  currently stored in the array.  In this situation the array  should  be
replaced  with  a list which will make things both simpler  and  faster  for
managing the array.

Dimming Lists

A  list  is dimensioned similar to an array except the word List is inserted
after the word Dim. Lists are currently limited to one dimension.

Here is an example of setting up a list:

    NEWTYPE.Alien
        flags.w:x:y
    End NEWTYPE

    Dim List Aliens.Alien(100)
The  difference  between a list and an array is that  Blitz2  will  keep  an
internal  count of how many elements are stored in the list (reset  to  zero
after a Dim List)  and an internal pointer to the current element within the
list (cleared after a Dim List).

Adding items to a list

A list starts out as empty, items can be added using the AddItem and AddLast
functions.  Because the list might be full both commands return  a  true  or
false to indicate whether they succeeded.

The following adds one alien to the previously dimmed list:

    If Additem(Aliens())
        Aliens()\x=Rnd(320),Rnd(200)
    Endif

Note  how  there is no index variable inside the brackets in either  use  of
Aliens().   Although Blitz2 will not flag an error when an  index  is  used,
indexes should never be used with list arrays.  The empty brackets represent
the current item in the list, in this case, the newly added item.

Because  AddItem  returns  false  when  the  list  is  full  we  can  use  a
While..Wend  loop  to fill an entire list with aliens  (then  kill  'em  off
slowly!):

    While Additem(Aliens())
        Aliens()\x=Rnd(320)
        Aliens()\y=Rnd(200)
    Wend

Page 28



The above loops until the list is full.  IS we wanted to add 20 aliens to  a
list we could use a For..Next but would still need to check if the list  was
full each time we added an alien:

    For i=1 To 20
        If Additem(Aliens())
            Aliens()\x=Rnd(320)
            Aliens()\v=Rnd(200)
        Endif
Next

Note  that  lists  can  be dimensioned to hold any  type  not  just  aliens!
(They're not just for games that is.)

Processing Lists

As  mentioned,  when an item is successfully added,  that item  becomes  the
current  item.  This current item may then be referenced by  specifying  the
list array name followed by empty brackets ( ).

To  process a list (loop through all the items added to a list),   we  reset
the  list pointer to the beginning using ResetList and then use the NextItem
command  to  step the pointer through the items in the list.  This  internal
pointer points to the current item.

The  following  moves  all the aliens in the list in  a  rather  ineffective
manner (towards the middle of the screen I suspect):

    USEPATH Aliens()

    ResetList Aliens()

    While Nextitem(Aliens())
        If \x>160 Then \x-1 Else \x+1
        If \y>100 Then \y-1 Else \y+1
    Wend

The  While Nextitem(Aliens())..Wend structure loops until each item  in  the
list  has  been the current item.  This means that any alien that  has  been
added to the list will be processed by the loop.

The  function NextItem returns false if the loop comes to  the  end  of  thr
list.

Again,  NextItem returns a true or false depending on whether there actually
is  a  next  item to be processed.  This example illustrates the convenience
lists offer over normal arrays,  no "for i= I to num" to step through arrays
using the old index method,  instead a clean While..Wend with a system  that
is faster than normal arrays!

PAge 29


Removing Items From a List

It  is  often  necessary  to  remove an item  from  a  list  while  you  are
processing it.  This may be achieved with Kililtem. This example again works
with the Aliens list:

    ResetList Aliens()

    While Nextitem(Aliens())
        If Aliens()\flags=-1 ;if flag=-1
            Killtem Aliens() ;remove item from list
        Endif
    Wend

Note:  after a Killtem,  the current item is set to the previous item.  This
means the While Nextitem() loop will not miss an item if an item is removed.
List Structure

Although  it  is  possible to access items in a list  by  treating  them  as
normal arrays with an index variable it should never be attempted.

The  order of items in a list is not always the same as the order  they  are
in  memory.  Each item contains a pointer to the item before  and  the  item
after.   When  Blitz2 looks for a next item it just  looks  at  the  pointer
attached  to  the  current  item,   its  physical  memory  location  is  NOT
important.  When an item is added to a list, an arbitrary memory location is
used,   the current item's NextItem pointer is changed to point to  the  new
item and its old value is given the new items Nextitem pointer.

Confused? Well don't worry,  just don't ever treat lists as normal arrays by
trying to access items with the index method.

The Pointer Type

The  pointer type in Blitz2 is a complex beast.  When you define a  variable
as a pointer type you also state what type it is pointing to.  The following
defines biggest as a pointer to type Customer.

    DefType *biggest.Customer

The  variable biggest is just a long word that holds a memory location where
some other Customer variable is located.

As  an  example  we  may have a large list of customers,  our  routine  goes
through them one by one,  if the turnover of a customer is larger  than  the
one  pointed  to  by  Biggest  then we point  Biggest  towards  the  current
customer: *biggest=CustomerArray()

Once  we  have  looped through the list we could print out the Biggest  data
just  as  if  it was type Customer when it is actually only a pointer  to  a
variable with type customer with Print *biggest\name.

Page 30


4. PROCEDURES

Introduction

A procedure is a way of 'packaging' routines into self contained modules.

Once  a routine is packaged into a procedure,  it can be 'called' from  your
main code,  parameters can be passed, and an optional value returned to your
main code.

Because  a  procedure contains its own 'local' variable space,  you  can  be
sure  that  none of your main or 'global' variables will be changed  by  the
calling  of the procedure.  This feature means procedures are very portable,
in  effect  they  can  be  ported  to other programs  with  out  conflicting
variable name hassles.

Procedures that return a result are called functions in Blitz2,   ones  that
do not are known as statements.

Functions and Statements in Blitz2 have the following characteristics:

. the number of parameters is limited to 6

. gosubs and gotos to labels outside a procedure's code is strictly illegal

.  any variables used inside a procedure will be initialized with every call
Statements

A procedure that does not return a value is called a Statement in Blitz2.

Here  is  an  example  of a statement type procedure which  prints  out  the
factorial of a number:

    Statement fact{n}
        a=1
        For k=2 To n
            a=a*k
        Next
        NPrint a
    End Statement

    For k=1 To5
        fact{k}
    Next
    MouseWait

Note  the  use of curly brackets { and } to both define parameters  for  the
procedure,  and in calling the procedure.  These are necessary even  if  the
procedure requires no parameters.

If  you  type in this program,  compile and run it,  you will  see  that  it
prints out the

Page 31


factorials  of  the  numbers from I to 5.  You may  have  noticed  that  the
variable k has been used in both the procedure and the main code.   This  is
allowable  because  the k in the procedure is local to the  fact  procedure,
and  is  completely separate from the k in the main program.  The k  in  the
main program is known as a global variable.

You  may  use up to six variables to pass parameters to a procedure  If  you
require  more  than this,  extra parameters may be placed in special  shared
global variables (see Shared below).

Also,  variables used to pass parameters may only be of primitive types, you
cannot  pass a NewType variable to a procedure however you can pass  pointer
types.

Functions

In  Blitz2,  you may also create procedures which return a value,  known  as
functions.   The  following  is the same fact  procedure  implemented  as  a
function:

    Function fact{n}
        a=1
        For k=2 To n
            a=a*k
        Next
        Function Return a
    End Function

    For k=1 To5
        NPrint fact{k}
    Next
    MouseWait

Note how Function Return is used to return the result of the function.  This
is  much more useful than the previous factorial procedure,  as we  may  use
the result in any expression we want. For example:

    a-fact(k}*fact{j}

A function may return a result of any of the 6 primitive types.  To inform a
procedure  what  type  of  result  you are  wanting  to  return,   the  type
descriptor may be appended to the Function command.  If this is omitted, the
current default type will be used (normally .q):

The following is an example of a string function:

    Function$ spc{n}
        For k=1 To n
            a$=a$+" "
        Next

    Function Return a$
    End Function
    Print spc{20},"0ver Here!"
    MouseWait

Page 32



Recursion

The  memory used by a procedure's local variables is unique not only to  the
actual  procedure,   but  to each calling of the  procedure.   Each  time  a
procedure is called a new block of memory is allocated and treed  only  when
the procedure ends.

The  implications  of  this are that a procedure  may  call  itself  without
corrupting it's own local variables.  This allows for a phenomenon known  as
recursion.   Here is another version of the factorial procedure  which  uses
recursion:

    Function fact{n}
        If n>2 Then n=n*fact{n-1 }
        Function Return n
    End Function

    For n=1 To 5
        NPrint fact{n}
    Next
    MouseWait

This  example  relies  on  the concept that the factorial  of  a  number  is
actually the number multiplied by the factorial of one less than the number.
Accessing Global Variables

Sometimes  it  is  necessary for a procedure to access  one  or  more  of  a
programs  global  variables.  For this purpose,  the Shared  command  allows
certain variables inside a procedure to be treated as global variables.

    Statement example{}
        Shared k
        NPrint k
    End Statement

    For k=1 To5
        example{}
    Next
    MouseWait

The  Shared  command tells Blitz2 that the procedure should use  the  global
variable  k  instead of creating a local variable k.  Try the  same  program
with  the  Shared  removed.  Now,  the k inside the  procedure  is  a  local
variable, and will therefore be O each time the procedure is called.

Procedures Summary

Blitz2  supports two sorts of procedures,  the function and  the  statement.
Both  are able to have their own local variables as well as access to global
variables through the use of the Shared statement.


Page 33



Up to six values can be passed to a Blitz2 procedure.

A  Blitz2  function can return any primitive type using the Function  Return
commands.

Using Assembler in Blitz Procedures

Procedures also offer an excellent method of incorporating assembly language
routines into Blitz programs.

The  Statement  or  Function is defined as usual with a list  of  parameters
enclosed in curly brackets.  When using assembler,  the parameters passed to
the procedure are loaded in data registers DO..DS.

Care  must  be taken to ensure that address registers A4-A6 are restored  to
their  initial  state  before the code exits from the  procedure  using  the
AsmExit command.

To  set the return value in assembler for Functions simply load the register
DO with the value before the AsmExit command.

For an example of an assembler procedure in Blitz, turn to page 63.

Page 34


5. BLITZ ERROR CHECKING AND DEBUGGING

Compile Time Errors

Blitz2  reports two types of errors.  Compile time errors  are  those  found
when  Blitz attempts to compile your code,  runtime errors occur  when  your
program is being executed.

The  first  type,  compile time errors,  cause a message to  appear  on  the
editor  screen.  When OK is selected you are returned to the offending  line
of code in your program.

Appendix 2 of the Blitz2 Reference Manual contains a description of all  the
possible  errors  at compile time.  The following list repeats  some  Blitz2
rules  that  have  to  be  abided by for your  program  to  be  successfully
compiled:

1.   Any  Blitz 2 functions (commands that return a value)  must have  their
     parameters inside brackets:

    If ReadFile(0,"ram:test")

2.    Blitz2  commands  that are not functions must not have  their  parameters
        in brackets:

    BitMap 0,320,256,3

3.    Using a .type suffix when referring to items in a NewType will cause a
        garbage at end of line error:

    person\name$="Harry" ;(drop the $)

4.   A numeric variable can only be one .type,  a MisMatched Type error will
 occur  if  you  attempt  to use a different .type suffix  further  down  the
program  with  the  same  variable   name  (with  the  exception  of  string
variables).

Of  course  there are many hundreds of mistakes that can cause your  program
to  fail to compile,  most will require a quick look in the Blitz2 Reference
Manual  to  check  syntax of a command and maybe cross reference  your  code
with one of the examples.

Don't forget the Help key to quickly check the syntax of a command.

Page 35



The CERR Directive

When  using  macros and conditional compiling you may wish to generate  your
own compile time errors.

The CERR directive is used to generate user defined compile-time errors. The
following  will halt the compiler and generate the message  "Should  Have  3
Parameters":

    CERR "Should Have 3 Parameters!"

See conditional compiling in Chapter 9 for more information on CERR.

Runtime Errors

Errors that occur while your program is executing are called runtime errors.
When  developing  programs  in Blitz2,  the Runtime  Error  Debugger  should
always be enabled on the Compiler Options window.  If it is not and an error
occurs the system will crash.

If  you  need to run your program without runtime errors enabled  for  speed
purposes  a SetErr directive should be included to stop the system crashing,
the system will then jump to the code listed after the SetErr.

The following line included at the top of your program is suggested:

    SetErr:End:End SetErr

Any  programs that use filehandling should always include some sort of error
trapping  to handle situations where the program cannot locate a  file,   or
the file is the wrong type.

Any  operating  system  based  software should  also  always  include  error
checking as Screens and Windows may fail to open due to low memory.

You  may  also  setup an error handler just for one section  of  code.   The
SetErr..errorhandler..End SetErr should be at the start of the  section  and
a ClrErr at the end of the section.

The following will flash the screen and end if LoadShapes fails:

    SetErr
        DisplayBeep_ 0
        End
    End SetErr

    LoadShapes 0,"filename"

    ClrErr

Page 36



The Blitz Debugger

If  a  runtime error occurs when a program is run from the editor the Blitz2
debugger  will be activated.  Of course RuntimeErrors must also be  enahleL1
in the compiler options requester.

The  debugger  will  not  be activated it there is an error-handler  already
enabled h1 the program using the SetErr command.

The  debugger  can  also  be  activated by using  the  CTRL/ALT  C  keyboard
combination,   clicking  on  the  "BRK gadget  of  the  debugger  window  or
including a STOP command h1 your program.

The  debugger  is  a  powerful tool in finding  out  causes  of  errors  and
locating bugs.  The ability to step back through code executed prior to  the
break  gives the prograrmmer an excellent understanding of how an error  has
occurred.   The follwing is a screenshot of the debugger after  the  program
encountered a STOP command.

Note  that by making the debugger window larger more of the program  can  be
viewed.

Page 37


The Debugger Gadgets

The following is a description of the debugger gadgets:

BRK

Click on this to stop a program running and enable the Blitz debugger.

STP        Use this to stop a program during Trace mode.

SKP
Skip causes the debugger to skip a command, program execution
will continue from the next command when then RUN.

TRC

Trace  mode  allows the programmer to single step through  their  code,   by
increasing the size of the debugger window program flow can be viewed.

RUN        RUN causes program execution to resume after being stopped.

<<

View  previous command history allows the programmer to review the  commands
that were executed prior to the program being stopped.

>>

View  forward  allows the user to forward through the command history  after
using the view previous gadget.

EXC

Execute  allows  the  programmer to manually enter a  Blitz  command  to  be
executed by the debugger.

EVL

Evaluate allows the programmer to view any variable simply by entering  it's
name after clicking on EVL.

Tracing program execution

The  debugger  allows  the  user to single step  through  or  trace  program
execution,   displaying  in it's window which  command  is  currently  being
executed.

Step  is  used to single step through your program,  each time you click  on
STP the debugger will execute the command pointed to by the arrow and stop.

Trace  steps  continuously through the code displaying each  command  as  it
goes. To stop the Trace use the STP gadget.

Level  is  used  to  change the trace level,  if Level is toggled  on,   the
debugger  will  not  trace or single step through the  inside  of  For..Next
loops but execute normally until the loop exits.

It  will  also  not  trace  the execution of any procedures  or  subroutines
called,  this is most useful for watching the program's main loop while  not
having to sit through the trace of each subroutine when called.

Page 38


Resuming Normal Execution

Program execution can return normally after the debugger is activated  using
the Run gadget.

If  the  debugger  was activated using the STOP command the  arrow  will  be
pointing  to  the STOP,  before continuing the command must be skipped  over
using  the Ignore command.  This is true for any command that has  caused  a
RunTime error and invoked the debugger.

To  return  to  the editor from the debugger either hit the  Escape  key  or
click on the close window gadget of the debugger Window.

Viewing command history

The  debugger keeps a record of the commands executed before the program  is
stopped in a large buffer.

The  Back-up  command  will step backwards from where  the  program  halted,
allowing  the  programmer  to view the previous  commands  executed  by  the
computer. A hollow arrow marks the current position in the history buffer.

The  Forward  command is used to step forwards through the  history  buffer,
attempting to step past where the program was stopped will produce a AT  END
OF BUFFER error.

These features are invaluable to following through program execution  up  to
where  the  program was halted.  If a program halted  in  the  middle  of  a
subroutine  or  procedure you can step backwards to find where  the  routine
was called from.

Direct Mode

While  the  debugger is activated the programmer has two tools available  to
examine the internal state of the program.

To find out the value of any variables the EVaLuate command can be used.   A
prompt  will  appear,   after typing the name of the  variable  and  hitting
return the value will be printed on the debugger display.

The  EXeCute command is used to run a Blitz2 command.  A prompt will  appear
and the programmer can then type in any Blitz2 command such as CLS or n=2().

Page 39


Debugger Errors

The  following errors may occur when using the direct mode commands Evaluate
and eXecute:

    Can't Create in Direct Mode

Occurs  if you try and Evaluate a variable that does not exist (hasn't  been
created) in the program.

    Library Not Available in Direct Mode

Occurs  when a Blitz2 command is eXecuted and is from a command library  not
used by the program.  If the program does not use strings for instance,  the
string  command  library will not be part of the  object  code  and  so  any
string type commands will not be able to be eXecuted.

    Not Enough Room in Direct Mode Buffer

This  error should never occur.  if it does the object butter  size  in  the
Compiler Options requester should be increased.

    AT END OF BUFFER

Occurs  if the programmer tries to view Forward of where the program stopped
(see viewing command history).

Page 40


6. BLITZ OBJECTS

Blitz2 Objects Overview
This  chapter  covers  the use and handling of Blitz2  objects,   structures
designed  to  control  multiple system elements such  as  graphics,   files,
screens etc.

Blitz2 looks after all memory requirements for objects including freeing  it
up when the program ends.

Although  most objects have their own specific commands,  the  standard  way
they  are handled in Blitz2 means the programmer is never faced with unusual
syntax.   Instead they can depend on a standard modular way  of  programming
the multitude o elements available in Blitz2.

The following is a list of the main Blitz2 objects:

Files            for sequential and random access DOS file handling
Modules            soundtracker compatible music objects
Blitzfonts        8x8 fonts for fast BitMap text output
IntuiFonts        any size fonts for Window text output
Shapes            standard Blitz2 graphics element
Palettes        colour palette structure
BitMaps            standard Blitz2 display element
Sounds            digitised sound sample element
Sprites            Blitz mode hardware sprite element
Screens            standard Intuition type screens
Windows            standard Inuition type windows
Gadgets            standard Intuition type gadgets
Menus            standard Intuition type menus

Object Similarities

Blitz2 objects all have a set of commands allowing the program to create  or
define them, manipulate and of course destroy them.

Most  objects have a chapter in the Blitz2 reference manual devoted to them,
outlining all the special commands used to create and manipulate the object.
All  Blitz2 objects can be destroyed using the Free command.  If  an  object
has  not been destroyed when a program ends,  Blitz2 will automatically Free
that object.

Free  BitMap 0 will free up all memory allocated for object BitMap 0,   this
is  useful when using objects temporarily and will need the memory later  in
the  program,   otherwise  it is usual to let Blitz2  free  up  all  objects
automatically when the program

Page 41



ends.

Object Maximums

Each object has its own maximum. this number defines how many of one type of
object  can be created and manipulated by the program.  The maximum  can  be
changed for each object in the Compiler Options window of the editor.

The runtime error Value Out Of Maximum Range means you have tried to use  an
object  number greater than that set in the maximums window of the  Compiler
Options.

Using an Object

Many  commands need previously created objects present to operate  properly.
For  example,   the Blit command,  which is used to place  a  shape  onto  a
bitmap, needs both a previously created shape object and a bitmap object.

When  you use the Blit command,  you specify the shape object to be  blitted
and Blitz will blit that shape onto the currently used bitmap.

    Use BitMap 0 ;make bitmap the currently used bitmap
    Blit 3,10,10    ;blit shape 3 onto currently used bitmap

The  Use  command in the previous example makes BitMap 0 the currently  used
bitmap.  Screens,  Windows and Palettes are three other Blitz2 objects  that
often need to be currently used, for commands to work properly.

It should also be noted that when an object is created,  it also becomes the
currently used object of it's class.

Blitz2  makes  extensive  use  of this currently  used  object  idea.   It's
advantages include faster program execution,  less complex looking commands,
and greater program modularity.

Page 42


Input/Ouput Objects

BitMap,   File  and  Window objects can all operate  as  1/0  devices.   The
ObjectInput  and ObjectOutput commands allow the user to channel  input  and
output to different places.

The Print command will always write to the current output object,  edit  and
inkey$ will always attempt to read from the current input object.

    WindowOutput 2; window 2 is the current output object
    Print "HELLO"
    BitMapinput 1 ;make bitmap 1 the current input object
    a$=Edit$(80)

Object structures (for advanced users)

Appendix I of the Blitz2 reference manual contains descriptions of  each  of
the  Blitz2  object's structures.  The Addr command  is  used  to  find  the
location in memory of a particular objects structure.

Advanced  users  can  use the Addr command with peek  and  poke  and  inline
assembler  routines  to  access important values in an  object's  structure.
This  is  often helpful with system type objects such as Screens and Windows
that contain pointers to their Intuition counterparts.

The  following  calls  the  system   command  ScreenToFront_  obtaining  the
location of the Inuition Screen structure from the Blitz2 Screen  object  in
memory.

    ScreenToFront_ Peek.l(Addr Screen(0))

This  next  listing  illustrates obtaining a Window's system  structure  and
assigning  it to a pointer type .Window.  AmigaLibs.Res should  be  resident
before running this example.

    FindScreen 0
    Window 0,10,10,100,100,9,"SIZE ME!",1,2
    *w.Window=Peek. I(Addr Window(0))
    WindowOutput 0
    Repeat
        ev.l=WaitEvent
        WLocate 0,0
        NPrint *w\Width
        NPrint *w\Height
    Until ev=$200

Note:  the NewType.Window refers to the system (Intuition)  window structure
where as the NewType .window refers to the Blitz2 window structure.

Page 43


Overview of the primary Blitz2 Objects

Screens

Screens  are  created using the Screen and FindScreen commands.   The  first
will  open  a  new  screen  while the second will make  an  existing  Screen
(usually the WorkBench screen) a Blitz2 Screen.

Free  Screen n should only be attempted after any Windows open on the Screen
are closed (freed) first.

Screen  objects both configure the resolution of the display and its palette
as  well  as being the place where Windows are opened.  Any Windows  opened,
RGB or UsePalette commands will use the currently used screen.

The  function Peek.l(addr Screen(n))  can be used to obtain the location  of
the system .Screen structure when calling system routines.

Windows

Windows  are created with the Window command.  Gadgets and menus are  always
added  to  the  currently  used  window while the  drawing  commands  WPlot,
WCircle, WLine and WBox all render to the currently used Window.

Window  objects  can  be  used for input/output using  the  WindowInput  and
WindowOuput commands.  The cursor position for input/ouput can be controlled
with the WLocate command.

Windows  can  be freed without the worry of freeing any attached  gadget  or
menulists.

Gadget and Menu lists

Gadgets and menus must be grouped together in Blitz objects known  as.   yes
you guessed it,  gadgetlists and menulists.  These lists are attached  to  a
Window  when the window is first created (opened).  This means that  gadgets
and  menus  should all be pre-defined in their lists at  the  start  of  the
program.

Palettes

A  palette  object contains RGB information for each of  the  colours  in  a
display.   Palettes are a little different to regular Blitz objects  in  the
following ways.

Use  Palette  will  set the current screen or slice to the  colours  in  the
palette.

The RGB command as well as the Red(),  Green() and Blue() functions apply to
the colours in the current Slice or Screen NOT in the current palette.

There  is  no  create palette command,  they are either created when  loaded
from  an  IFF  file or when using PalRGB,  if no palette object exists  with
either command Blitz2 will create one.

Page 44


BitMaps

A  bitmap refers to the array of pixels that make up the display.  A  bitmap
can  either be created with the BitMap command,  loaded from disk or fetched
from a Screen using the ScreensBitMap command.

A  Bitmap command can be freed using the Free BitMap n command,  you can not
free bitmaps created with the ScreensBitMap command.

As  with  windows,  bitmaps can be used as input/ output  devices  with  the
BitMapInput  and  BitMapOutput   commands.   These  are  used  primarily  in
BlitzMode.

In  BlitzMode  the  keyboard  should be enabled  with  BlitzKeys  On  before
attempting to use BitMapInput.

When  using  BitMapOutput the Locate command can be  used  to  position  the
cursor.

Shapes

Shapes  are  used  to contain graphic images.  They can  be  initialized  by
either  loading them from disk or being clipped from a bitmap  object  using
the GetAShape command.

Shapes are freed using the standard Free Shape n syntax.  Shapes should  not
be  freed  if  they are used with gadgets or menu items until  the  relevant
gadget or menulist is freed first.

There  are  many powerful commands in Blitz2 to manipulate shapes  including
rotation and scaling.

Sprites

Sprites  are  initialized by either loading them from disk or  converting  a
shape object to a sprite object using GetaSprite.  The shape object  can  be
freed once it has been converted to a sprite.

Free Sprite n will free a sprite

Sprites can currently only be used in Blitz mode however in Amiga mode,  the
pointer can be assigned to a single sprite object.

Slices

A  slice is used to configure a display in Blitz mode.  They are initialised
with the Slice command.

Unlike other objects,  single slices cannot be freed.  FreeSlices is used to
free all slices currently initialised.

The commands Show, ShowF, ShowB and ShowSprite all use the currently used

Page 45


slice.   The RGB command also affects the colour registers in the  currently
used slice as does the Use Palette command.

Files

Unlike  other  Blitz2  objects  files are  opened  and  closed  rather  than
initialised and killed.

Files  are  initialised  with the OpenFile(),  ReadFile()   and  WriteFile()
functions.   Unlike other Blitz2 objects a function is used so  the  program
can tell if the file was successfully opened.

The  CloseFile n command is used to 'free' a file object.  The command  Free
File n may also be used,  unlike other objects it is best to close all files
yourself rather than rely on Blitz2 to close them when the program exits.

A  file  is  of  course an input/output object,  the commands FileInput  and
FileOutput are used to direct input and output to files.

Get,   Put,  ReadMem and WriteMem require file# parameters  and  so  do  not
require the use of FileInput and FileOutput commands.

Objects Summary

Blitz2's objects are custom data structures used by the libraries to  handle
a whole assortment of entities.  Blitz2 manages the memory required by these
structures, freeing them automatically when a program ends.

They provide a simple interface to many of the more complex Blitz2 commands.
Parameter  passing  is  minimised  as  many  of  the  Blitz2  commands  take
advantage of the currently used object.

As  libraries are upgraded and added to Blitz2,  more objects will be  added
and versatility and functionality of existing objects will be increased.

Page 46

7. BLITZ MODE


Introduction to Blitz Mode

Although  the  Amiga's operating system is very powerful,  it's  ability  to
take  full  advantage of the graphics capacity of the  machine  is  limited.
Blitz  mode  is for programmers wanting to produce smooth animated  graphics
for games and the like.

The  command Blitz puts your program in Blitz mode.  When this  happens  the
operating system is disabled and your program takes over the whole  machine.
This  means  that  it  will  not multi-task and file  access  is  no  longer
possible.

The  benefits of Blitz mode are that programs run a lot quicker and  display
options such as smooth scrolling and dual-playfield are possible.

Blitz mode is not a permanent state,  when your program re-enters Amiga mode
or  exits,   the operating system is brought back to life as though  nothing
happened.

Careful attention must be payed regarding entering Blitz mode,  version  1.3
and  older  of the operating system can take up to 2 seconds  to  flush  any
buffers after a file is closed.  You should always ensure that absolutely no
disk or file access is taking place before entering Blitz mode.  At the time
of  this  writing,   no  software method of  achieving  this  has  yet  been
discovered.   The best we can suggest is that a VWAIT 100 should  always  be
executed before using Blitz mode.

Slice Magic

The  designers  of  the Amiga hardware have implemented  many  features  for
acheiving smooth,  fast graphics.  After entering Blitz mode the display  is
controlled  using Slices.  Slices are much more flexible than the  operating
system's  Screens,   they allow features such as smooth  scrolling,   double
buffered displays and much more.

The  ability to have more than one slice means that the display can be split
into different regions each with their own resolution.

The  following is a description of the main display features accessible with
slices:

Page 47


Smooth Scrolling

Smooth  scrolling  is  acheived by displaying only  a  portion  of  a  large
bitmap.  The Amiga hardware enables us to move the display window around the
inside of a large bitmap as the following diagram shows:

The display window represents what is shown on the monitor,  as we move  the
display  window  across the bitmap to the right the  image  we  see  on  the
screen scrolls smoothly to the left.

The Blitz commands Show, ShowF and ShowB allow us to set the position of the
display window inside the bitmap.

The  above  diagram  limits the amount we can scroll  to  the  size  of  the
bitmap.  By duplicating the left portion of the bitmap on the right  we  can
smoothly scroll the display across,  and when it reaches the right, reset it
back  to  the far left.  As there is no change when the display is reset  to
the left the illusion of continuous scrolling is created.

The  above  left  right scenario also applys to vertical scrolling  (up  and
down).

Dual-Playfield

In  some  situations,  the display will be made up of  a  background  and  a
foreground.  The Amiga has the ability to display one bitmap on top  of  the
other called dual- playfield mode to achieve this effect.

In  a  dual-playfield display,  two 8 colour bitmaps can be displayed,   one
infront of the

Page 48


other,   any  pixels  set  to colour zero in the  front  playfield  will  be
transparent  letting the back playfield show through.   Each  playfield  can
have its own colours.

Copper Control

Smooth  animation  is acheived by moving graphics in  sync  with  the  video
display.   The  display is created by a video beam that redraws  the  screen
line by line every 50th of a second.  Often,  it is useful to sync things to
the  vertical  position of the vertical beam.  This is  acheived  using  the
Amiga graphics co-processor known as the Copper.

Blitz2 offers several ways of taking advantage of the copper hardware.   The
most  popular  is to change the colour of the background colour  to  produce
rainbow  type effects on the display.  This is acheived using  the  ColSplit
command.

Those  with  a good knowledge of the Amiga hardware may wish to program  the
copper  to  make other changes at different vertical places,   this  can  be
acheived using the CustomCop command.

The Blitter

The  Amiga has custom hardware specifically to transfer graphic images  onto
bitmaps known as the glitter.  Blitz2 offers several ways of blitting shapes
onto  a  bitmap  and a special Scroll command to shift  areas  of  a  bitmap
around using the blister.

The  following is a brief overview of the various blister based commands  in
Blitz2:

Blit     used to put shapes onto bitmaps.

QBlit

same as Blit but Blitz2 remembers where the shape was put and will erase  it
when it is time to move the shape somewhere else on the bitmap.

BBlit

same as QBlit but when it is time to move the shape,  instead of erasing the
shape, Blitz2 replaces what was on the bitmap previous to the BBlit.

SBlit

sames as Blit but with a stencil feature which protects certain areas of the
bitmap from being blitted on.

Block

fast  version of Blit that works only with rectangular shapes a multiple  of
16 pixels wide.

Page 49


ClipBlit Slow version of Blit which will clip the shape to fit inside the bimap.

Scroll used to copy sections of a bitmap from one position to another.

QAmiga Mode

It  is  also  possible to jump out of Blitz mode and back into  Amiga  mode.
This can done using either the QAmiga or Amiga statement.

Using  Amiga to go back into Amiga mode will fully return you to the Amiga's
normal display, complete with mouse pointer.

Using QAmiga will return you to Amiga mode,  but will not affect the display
at  all.  This allows your Blitz mode programs to jump into Amiga  mode  for
operations such as file I/O,  then to jump back to Blitz mode without having
to destroy a Blitz mode display.

An Important note!!!!!

You  should always ensure that absolutely no disk or file access  is  taking
place before entering Blitz mode.  At the time of this writing,  no software
method of achieving this has yet been discovered.

By following these guidelines using Blitz mode should be pretty safe:

.   Always wait for the floppy drive light to go out if you have saved  some
source  code before Compiling/Running a program which launces straight  into
Blitz mode.

.   A590  Hard drive users - always wait for the second blink of  the  drive
light when using Workbench 1.3,  2.0 users have there buffers flushed in one
go.

.   If you use the QAmiga statement for the purpose of writing data to disk,
it's  a  good idea to execute a delay before going back to Blitz mode  -  In
effect,  simulating the above. Executing a VWait 250 will provide a delay of
about five seconds - a safe delay to use. After reading data use a VWait 50.
Another  important thing to remember about Blitz mode is that  any  commands
requiring  the  presence  of the operating system become  unavailable  while
you're in Blitz mode.  For example, if you attempt to open a Window in Blitz
mode,   you will be greeted with an 'Only available in Amiga Mode' error  at
compile  time.  For this reason,  the Reference Guide clearly  states  which
commands are available in which mode.

The Blitz,  Amiga,  and QAmiga statements are all compiler directives.  This
means they must appear in applicable order in your source code.

Summary

Page 50


Blitz2 provides two environments for your programs to execute in. Amiga mode
should  be  used for any applications software and whenever your game  needs
to  load  data  from disk.  Blitz mode is for programs  that  need  to  take
advantage  of  the special display modes we have provided in Blitz2.   These
provide  performance that is just not available in Amiga mode but will  halt
the Amiga's operating system.

To conclude,  the only time it is acceptable to close down the Amiga's multi
tasking environment is when the software is dedicated to entertainment.  any
applications  software that uses Blitz mode will  NOT  be  welcomed  by  the
Amiga community.

Page 51


8. ADVANCED TOPICS

Resident Files

To  make writing programs which manipulate large number of NewTypes,  macros
or constants easier, Blitz2 includes a feature known as resirlentfiles.

A  resident  file  contains a pre-compiled list  of  NewTypes,   macros  and
constants.  By creating resident files, all these definitions can be dropped
from the main code making it smaller and taster to compile.

To  create  a resident file you will need a program which contains  all  the
NewTypes.  macros and constants you want to convert to resident file format.
The following is an example of a such a program:

    NEWTYPE.test
        a.l
        b.w
    End NEWTYPE

    Macro mac
        NPrint "Hello"
    End Macro

    xconst= 1 0

Now,  to convert these definitions to a resident file, all you need to do is
COMPILE&RUN the program, then select CREATE RESIDENT from the COMPILER menu.
At  this point,  you will be presented with a file requester into which  you
enter the name of the resident file you wish to create.  That's all there is
to creating a resident file!

Once  created,   a resident file may be installed in any program  simply  by
entering the name of the resident file into one of the 'RESIDENT' fields  of
the compiler options requester.  Once this is done,  all NewType,  macro and
constant  definitions contained in the resident file will  automatically  be
available.

The resident file AMIGALIBS.RES contains all the structures,  constants  and
macros  associated  with the Amiga operating system.   Those  familiar  with
programming  the operating system will find not having to  include  all  the
usual library header files will save minutes every compile time.

Page 53


Operating System Calls

Much effort has been made to let the Blitz2 programmer make the most of  the
Amiga's powerful operating system.

Calling Operating System Libraries

Often  the  programmer  with a good knowledge of the Operating  System  will
want  to  access  routines that have not been supported  by  the  'internal'
Blitz2 command set.  All routines in the Exec,  Intuition,  DOS and Graphics
libraries  are  accessible  from  Blitz2  (see  appendix  5  in  the  Blitz2
Reference Manual).

Support  for  other Amiga standard libraries is available by purchasing  the
Blitz2 advanced programmers pack from Acid Software.

The  following is an example of calling routines in the Amiga ROM's graphics
and intuition libraries:

FindScreen 0                    ;use workbench screen

;open gimmezerozero window

Window 0,0,10,320,180,$408,"",1,2
rp.l=RastPort(0)            ;get rastport for window
win.l=Peek.l(Addr Window(0))        ;find window structure

DrawEllipse_rp, 100,100 ,-50,50        ;graphics library
MoveWindow_win,8,0            ;intuition library
BitMap 1,320,200,2            ;setup work bitmap
Circlef 160,100,100,1            ;draw something

;then transfer it to window

BltBitMapRastPort_ Addr BitMap(1),0,0, rp,0,0, 1 0O, 1 00,$c0

WaitEvent

The  final  command  BltBitMapRastPort_  is  very  useful  for  transferring
graphics drawn with the faster bitmap based Blitz2 commands onto  a  Window.
This is a very system friendly way of acheiving this objective.

Page 54


Accessing Operating System structures

With  the  file  AMIGALIBS.RES resident (see start of  chapter)   even  more
control of the operating system is possible.  The following is an example of
accessing operating system structures.

    ;variable *exec points to the ExecBase struct
    ;variable *mylist points to a List type
    ;variable *mynode points to a system node

    *exec.ExecBase=Peek.1(4)
    *mylist. List=*exec\LibList
    *mynode.Node=*mylist\lh_Head

    While*mvnode\ln_Succ
        a$=Peek$(*mynode\1n_Name);print node name
        NPrint a$
        *mvnode=*mvnode\ln_Succ:qo to next node
    Wend

    MouseWait

The  use of the asterisk in *variablename.type means that instead of  Blitz2
creating  a variable of a certain type it actually just creates a  'pointer'
to that type.  The type (structure) can then be accessed just like it was an
internal Blitz2 variable.

The  command  Peek$  is an excellent way of retrieving text  from  operating
system  structures,  it reads memory directly into a Blitz2 string  variable
until it hits a null (chr$(0)).

Locating Variables and Labels in Memory

The ampersand ('&')  character can be used to find the address of a variable
in the Amiga's memory. For example:

    ;
    ; An example of using '&' to find the address of a var.
    ;
    Var.l=5
    Poke. I &Var, 10
    NPrint Var
    MouseWait

This is similar to the VarPtr function supplied in other BASIC's.

When  asking for the address of a string variable,  the returned value  will
point to the first character of the string.  The length of the string is a 4
byte value, located at the address-4.

The '?' character can be used to find the address of a program label in  the
Amiga's

Page 55


memory. For example:

    ;
    ;An example of finding the address of a program label
    ;
    MOVE #1 0,There            ;wo! assembly code on this line
    NPrint Peek.w(?There)
    MouseWait
    End
    ;
    There:Dc.w 0            ;wo! and again here

These  features  are really only of use to programmers  with  some  assembly
language experience who need unconventional means for their ends.

Constants

A 'constant',  in BASIC programming terms,  is a value which does not change
throughout the execution of a program. The 5 in a=5 is a constant.

A  hash  sign  (#)  before a variable name means that it is a  constant  (no
longer a variable!)  and cannot change in value when the program is running.
#width=320 means the variable #width is a constant and will always be  equal
to 320.

Constants have the following properties:

. are faster than variables and do not require any memory

. make programs more readable than using numbers

. can be used in assembler

. can be used with conditional compiling evaluations

. can only hold integer values

. make it easier to change a constant amount used throughout a program

. can be altered through the source at compile time but NOT at runtime

The  most  important aspect of constants from a BASIC programmers  point  of
view  is that any 'magic numbers' that appear throughout their code  can  be
replaced by meaningful words such as #width.

If the program ever has to be modified to work with a new width,  instead of
going through all the source changing any mention of the numbers '320',  the
programmer  can just change the constant equate at the top  of  the  program
#width=320 to #width=640 etc.

Page 56

Conditional Compiling

Conditional  compiling allows the programmer to switch the compiler  on  and
off  as  it reads through the source code,  controlling which parts  of  the
program are compiled and which are not.

Conditional  compiling  is useful for producing different  versions  of  the
same software without using two different source codes.  It can also be used
to  cripple a demo version of the software or produce different programs for
different hardware configurations.

Tracking  down  bugs can also involve the use of conditional compiling,   by
turning  off any unnecessary parts of the code it becomes easier to pinpoint
where  exactly the error is occurring.  However we hope the Blitz2  debugger
will make this practice obsolete.

The conditional compiler directives are as follows:

CNIF     -compiler on if numeric comparison is true, off otherwise
CSIF     -compiler on if string comparison is true, off otherwise
CELSE     -switch compiler from previous state on=>off off=>on
CEND     -end of conditional block (restores previous state)

The compiler has an internal on/off switch,  after a CNIF or CSIF comparison
the compiler switches on for true,  off for false.  A CELSE will toggle  the
compiler  switch and the CEND will restore the on/off state to that  of  the
previous CNIF/CSIF.

CNIF/CEND blocks can be nested.

It is important to remember that the CNIF directive only works with constant
parameters - for example,  '5',  '#test' - and not with variables.  This  is
because  Blitz2 must be able to evaluate the comparison when it is  actually
compiling, and variables are not determined until a program is actually run.

The following code illustrates using conditional compiling:

    #crippled=] ;is a crippled version

    NPrint "Goo Goo Software (c)1993"

    CNIF #crippled=]
        NPrint "DEMONSTRATION VERSION"
    CELSE
        NPrint "REGISTERED VERSION"
    CEND
    ;
    ; and later on in the program...
    ;
    .SaveRoutine
    CNIF #crippled=0;only if not crippled
    ;
    ;do save routine
    ;
    CEND

Page 57


    Return

The  benefit over using a straight If crippled=O..EndIf is that the crippled
version  of  the above code will not contain the saveroutine in  the  object
code so that there is no way it can be un-crippled by hackers.

The  conditional compiler directives however come into their own when  doing
macro programming.

Macros

Macros  are  a  feature  usually only found in  Assemblers  or  lower  level
programming languages.  They can be used to save typing,  to replace  simple
procedures  with  faster 'inline' versions,  or at their  most  powerful  to
generate code that would be impractical to represent with normal code.

A  macro  is defined in a Macro name..End Macro structure.  The code between
these  two  commands  is not compiled but placed in the  compiler's  memory.
When  the compiler reaches a !macroname it then inserts the code defined  in
the macro at this point of the source code.

The following code:

    Macro mymacro
        a=a+1
        NPrint "Good Luck"
    End Macro

    NPrint "Silly Example v1.0"
    !mymacro
    !mymacro
    MouseWait

is expanded internally by the the compiler to read:

    NPrint "Silly Example v1.0"
        a=a+1
        NPrint "Good Luck"
        a=a+1
        NPrint "Good Luck"
    MouseWait

Page 58


Macro Parameters

To  make things a little more useful,  parameters can be passed in  a  macro
call  using  the squigly brackets { and ).  These parameters,   are  firstly
inserted into the macro text,  then the macro text is inserted into the main
code.

When  a  macro is defined the use of the back apostrophe (above the TAB  key
on the Amiga keyboard)  before a digit or letter ( 1-9, a-z) marks the point
where a parameter will be inserted

The following illustrates passing two parameters to a macro:

    Macro distance
        Sqr('1 *'1 +'2*'2)
    End Macro

    NPrint !distance{20,30}

    MouseWait

the compiler expands the nprint line to read:

    NPrint Sqr(20*20+30*30)

replacing every 'I with the first parameter and '2 with the second etc.

If  there  are  more than 9 parameters letters are used:  'a signifying  the
tenth parameter 'b the eleventh and so on.

Parameters can be any text,  the { 20,30 } could just as easily been { x,y )
in the previous example.

Note:   when passing complex expressions as parameters care should be  taken
to make sure parenthesis are correct:

    !distance{x*1 0+20,(y*1 0+20)}

will expand to

    Sqr(x*1 0+20*x*1 0+20+(y*1 0+20)*(y*10+20)}

The  above  does  not  expand correctly for the  first  half.   Due  to  the
parenthesis  around  the  second  parameter  the  second  half  does  expand
properly.

Page 59

The 'O Parameter

The 'O parameter is special,  it returns the number of parameters passed  to
the  macro.  This is useful for both checking to see that the correct number
of  parameters  was  passed as well as generating  macros  that  can  handle
different numbers of parameters.

The  following  macro  checks  to  see if two  parameters  were  passed  and
generates a compile time error if there was not:

    Macro Vadd
    CNIF '0=2
        '1='1+'2
    CELSE
        CERR "Illegal number of '!Vadd' Parameters"
    CEND
    End Macro

    !Vadd{a}

If  you  compile  and run this program,  you will see that it  generates  an
appropriate error message when '!Vadd{a)' is encountered.  The CERR compiler
directive  is  a special directive used to generate a custom  error  message
when a program is compiled.

Recursive Macros

Macros  are  recursive and can call themselves,  the following macro  prints
the  first  parameter  and then calls itself,  minus  the  first  parameter,
effectively  stepping through the list of parameters  passed  until  a  null
character (no parameter) is reached.

    Macro dolist ;list upto 16 variables
        NPrint '1
        CSIF "'2">""
        !dolistt'2,'3,'4,'5,'6,'7,'8,'9,'a,'b,'c,'d,'e,'f,'g}
        CEND
    End Macro
    !dolist {a,b,c,d,e,f,g,h,i}
    MouseWait

Page 60


Replacing Functions with Macros

Macros are an excellent replacement for functions that do not use any  local
variables but need to generate more than one return variable.  The following
macro  project takes x,  y,  z coordinates and projects them onto a  2D  x,y
plane. It can then be used to generate x,y projections for drawing.

    Macro project #xm+'I *9-'2*6,#ym+'1 *3+'2*(i-'3*7:End Macro

    #xm=320:#ym=256

    Screen 0,28:ScreensBitMap 0,0

    For z=-1 5 To 1 5
        For y=-15 To 15
            Forx=-15To15
                Circlef !project{x,y,z},3,x&y&z
            Next
        Next

    Next

    MouseWait

The CMake Character

A  special  character known as the cmake character can be used  to  evaluate
constant expressions and insert the literal result into your code.  This can
be  very  useful for generating label and variable names when a  combination
of  macro parameters and constant settings are needed to generate the  right
label.

    vaR=20
    var3=30

    Macro Ivar
        NPrint var~'1~
    End Macro

    !Ivar(2+1 }

    MouseWait

The  above example without the cmake characters ~ would print the  value  21
as  Blitz2  would  expand  the the code after the  NPrint  to  read  var2+1,
instead  it  evaluates  the  expression between  the  cmake  characters  and
generates a 3 which it then inserts into the macro text.

Page 61

Inline Assembler

It  is  possible to include 68000 machine code inside Blitz2 programs  using
the  inline  assembler.  This offers the experienced  programmer  a  way  of
speeding  up  their  programs  by replacing  certain  routines  with  faster
machine code equivalents.

There are three methods of including assembler in Blitz2:

. in line using the GetReg and PutReg commands to access variables

. inside statements and functions

. developing custom Blitz2 libraries

GetReg & PutReg

The  GetReg and PutReg commands allow the assembly programmer access to  the
BASIC  variables in the program.  The following listing illustrates the  use
of GetReg and PutReg:

    a.w=5            ;use words
    b.w=10
    GetReg dO,a        ;value of a=>dO
    GetReg d1 ,b    ;value of b=>dl
    MULU dO,d1
    PutReg dl ,c.w     ; value of dl=>c
    NPrint c
    MouseWait

The  next  example inverts the first bitplane of bitmap  0.   Note  how  any
complex  expression can be used after a GetReg command.  Because GetReg  can
only use data
registers, we place the location of the bitmap structure in dO and then move it to aO.

    Screen 0,3
    ScreensBitMap 0,0
    While Joyb(O)=0
        VWait 1 5
        Gosub inverse
    Wend
    End

    inverse:     ;memory location of bitmap struct=>dO
        GetReg dO,Addr BitMap(O)
        MOVE.I dO,aO
        MOVEM (aO),dO-d1
        MULU dO,d1
        LSR. 1#2,d 1
        SUBQ#1,d1
        MOVE.I 8(aO),aO
    loop:
        NOT.I (aO)+
        DBRA    d1,loop

Page 62



    Return

Using Assembler with Procedures

A  more efficient method of using assembler in Blitz2 is to put machine code
routines  inside  functions  and statements.  Parameters  are  automatically
placed  in d0-d5 and if using functions,  the value in register dO  will  be
returned to the calling routine.

The  following  listing  illustrates the use of  assembler  in  a  statement
qplot{}  which  sets a pixel on the first bitplane of the  bitmap  supplied.
Note  how more than one assembly instruction can be used per line of  source
code.

    Statement qplot{bmap.l,x.w,y.w}

        MOVE.I dO,aO:MULU (aO),d2
        MOVE.I 8(aO),aO:ADD.I d2,aO
        MOVE dl,d2:LSR#3,d2:ADD d2,aO:BSET.b d1,(aO)
        AsmExit
    End Statement

    Screen 0,1
    ScreensBitMap 0,0
    bp.l=Addr BitMap(O)
    For y.w=0 To 199
        For x.w=0 To 319
            qplot{bp,x,y}
        Next
    Next
    MouseWait

Programmers wanting to develop their own libraries of machine code  routines
should  purchase  the Blitz2 advanced programmers pack from  Acid  Software.
Blitz2  contains an extremely powerful library system giving the experienced
machine  code  programmer a highly productive and  powerful  environment  to
develop advanced software.

Page 63


9. PROGRAMMING TECHNIQUE & OPTIMIZING

Label and Variable Names

The  following are rules that must be conformed to when using  variable  and
label names in Blitz2.

. names can be of any length

. they must start with a letter (a..z, A..Z) or an underscore

. must only contain alphanumeric chars and underscores

. must not start with the same letters as any Blitz2 command

Also,   label  and  variable names in Blitz2 are  always  treated  as  case-
sensitive,   this  means that the variables myship and MyShip  are  entirely
different.

Style

There  are  many  variable  and  label   naming  approaches  that  can  make
programming much easier.  The following are a few guidelines that  can  help
keep  things  in  control as your program grows in size and  more  and  more
variables and labels are in use.

Consistency is essential,  if you use any of the following styles,  stick to
them.

By  separating different groups of variables and labels with  the  following
methods, names can have added meaning.

. full caps "NAME", inital cap "Name" and lower case "name"

. letters "l", words "Loop" and double words "MainLoop"

. initial underscore "_loop" and mid underscores "main_loop"

. numeric suffixes such as "loop!", "loop2" etc.

Nomenclature  is  a  personal  this by sticking  to  a  certain  style  with
variable and label names many problems with debugging can be avoided.  Using
good  names for everything can make your program far more readable and  wild
greatly aid in finding mistakes.

Page 65

Common naming related problems

The  following is a summary of certain problems that can arise when variable
and label names become messy.

Using  the wrong variable name will often not flag an error.  If it has  not
previously been assigned,  Blitz2 will create a new variable with a  default
value  of  zero.   Avoiding a mix of different naming  styles  will  greatly
reduce these mistakes.

Forgetting  variable names can slow program development,  by  using  logical
names and keeping a list of your main variables on a scrap of paper next  to
your keyboard helps keep things organised.

Using  lengthy  names can aid readability,  however it  will  also  increase
incidents of typing errors and slow development.

Use  of rude or obscene labels can make programming a little more enjoyable,
however it should be avoided if your source code will be read by others.

Remarks and Comments

Unlike  other BASIC's that use the REM statement,  Blitz2 uses the semicolon
character.   Any text after a semicolon on a line will  be  ignored  by  the
Blitz2 compiler. This feature is used to document programs.

Adding  remarks,  the programmer can document each routine in a program  for
future reference.  One of the main curses of programming is having to return
to  a  section of code developed earlier only to find you can not make  head
or tail of its logic.

Although it can seem a little tedious,  adding accurate explanations of each
routine as you write it will save many headaches later.

A section of documentation at the top of programs is also useful,  copyright
information,   lists of bugs fixed and when as well as full descriptions  of
all main variables should all be maintained at the top of your program.

Page 66


Structured programming techniques

The  main technique in developing structured programs is a method  known  as
indenting.  Indenting means that instead of each line being flush  with  the
left  margin,  spacing is inserted at the start of the line to  'indent'  it
across the page.

Indenting  lines  of code that are 'nested' inside loops  or  other  program
flow  structures creates a useful aid in visualizing the structure  of  your
source code.

The  Blitz2 editor has several features for indenting code.  The tab key  is
used  to  move the cursor across the page.  By changing the tab  setting  in
Ted's defaults requester the size of indent can be altered.

By highlighting a block of code,  block tab and untab (Amiga [ and Amiga  ])
will move the whole block left or right.

Shift cursor left will move the cursor to the same indent as the line above.
Keeping things modular

There  is nothing more valuable than good initial planning when it comes  to
developing software.  Breaking down your project into modular pieces  before
you start is a must to avoid the creation of huge spaghetti nightmares.

After  deciding on how each section of the program is going to  function  it
is  usually  best  to start with the most difficult sections.   Getting  the
hardest  bits  going first while the program is small  can  save  a  lot  of
headaches in the long run.

Time  spent  waiting  for  your program to compile  &  initialize  compounds
itself  when you are bug hunting or making small adjustments  to  a  certain
section of code.  In these situations it is usually best to remove the  code
from  the main program,  spend an hour writing a shell that you can test  it
in and then set about making it bullet proof.

A few things to keep in mind when developing routines:

. snake sure it will handle all possible situations called for

. convince yourself you are using the most efficient method

. keep it modular i.e. the routine must return to where it was called

. keep it well documented

. include comments regarding global variables and arrays it uses

. make sure it's bullet proof (won't fall over with bad parameters)

. indent nested code and limit lengths of lines to aid readability

Page 67


Along the way...

Besides keeping routines well documented it is always a good idea to keep  a
piece  of  paper handy to jot down the important bits.  Lists  of  variables
that  are  common  between  routines as well as  things  still  'to  do'  in
unfinished routines should always be written down.

The  'to  do' list is always a good way of thinking out all the problems  in
advance.   Always  keep  in  mind what extra  routines  will  be  needed  to
implement the next one on the list.

One  of  the  biggest mistakes a programmer can make is to start  a  routine
that  needs all sorts of other routines to function.  By starting  with  the
standalone/ independent bits you can make sure they are working.  This keeps
you  well  clear  of  the  headaches caused where  you  have  just  added  5
routines,  tested none of them and are trying to find a bug which  could  be
located in any one of them.  Developing a modular approach to programming is
definately the most effective way of finishing a piece of software.

Keeping your code readable.

Keeping  your  code readable is next on the list of requirements  that  will
aid in the completion of a piece of software.

The  two main keys to readability are indenting nested code and keeping  the
amount of code on one line to a minimum.

The following is an illustration of indenting nested code:

    If ReadFile (0,"phonebook.data")
        Filelnput 0
        While NOT Eof(0)
            If Additem(people())
                For i=0 To #num-1
                \info[i]=Edit$(1 28)
                Next
            Endif
        Wend
    Endif

This  method  means  that it is very easy to see at a glance  what  code  is
being  executed  inside  each  structure.  Using  this  method  it  is  very
difficult  to  make  a  mistake like leaving out the  terminating  EndIf  or
Wend's  as  just by finding the line above at the same level of  indentation
we can match up each Wend with it's corresponding While etc.

Page 68

Optimising Code

It  is always important to have a firm grasp on how much time is being taken
by certain routines to do certain things.  The following are a few things to
keep  in  mind  when  trying to get the best performance  from  your  Blitz2
programs.

Performance  is  most  Important with arcade type  games  where  a  sluggish
program will invariably destroy the playability of the game.  However, it is
also  important in applications and other types of software to  keep  things
as  efficient as possible.  Anything that makes the user wait  will  detract
from the productivity of the package in general.

Algorithms

The  most  Important  key to optimising different routines  is  the  overall
approach  taken to implementing them in the first place.  There will  always
be  half  a dozen ways of approaching a problem giving half a dozen possible
solutions.   In programming,  it is usually best to pick the  solution  that
will produce the result in the quickest time.

Loops

When  looking for ways to optimise a routine the best place to start  is  to
examine  the  loops (for..next,  while..wend etc.).  The time  it  takes  to
perform  the  code  inside a loop is multiplied by the number  of  times  it
loops.   This may seem rather logical but often programmers will equate  the
number of lines of code in a routine to the time taken to execute it.

The code:

    For i=1 to 100
        Nprint "hello"
    Next

Will take exactly the same amount of time as typing:

    For i=1 to 1
        Nprint "hello"
    Next

one hundred times, which will equate to 300 lines of code!

Once one can visualize loops expanded out,  the notion that if anything  can
be removed from inside a loop to before or after the loop then DO IT!

Page 69


Lookup tables

Replacing  numeric  functions with look up tables is  an  effective  way  of
gaining excellent speed increases.  A look up table or LUT for short,  is an
array  that  contains all the possible solutions that the  numeric  function
would be expected to provide.

The  most common example of using LUPs for healthy speed increases  is  when
using  trig  functions such as Sine or Cosine.  Instead of calling  the  Sin
function,  an array containing a sine wave is created, the size of the array
depends on the accuracy of the angle parameter in your program.

If  a was an integer variable containing an angle between 0 and 360 we could
replace  any  Sin  functions such as x=Sin(a* I t3()/pi)   with  x=siniup(a)
which  will  of course be more than 10 times as quick.  The array  would  be
setup in the program initialisation as follows:

    Dim siniup(360)
    For i=0 To 360
        sin|up(i)=Sin(i*1 80/pi)
    Next

Using Pointers

When doing many operations on a particular subfield in a NewType a temporary
pointer  variable  of the same subfield type can be created  and  that  used
instead of the larger (and slower) path name:

    UsePath a(i)\alien\pos

replaced by:

    UsePath *a
    *a.pos=a(i)\alien

Testing Performance

Often  it  is  important to test two different routines to see which  offers
the faster solution.  The easiest way is to call each of them 5000 times  or
so and time which is quicker by hand.

When  writing arcade games that will be performing a main loop  each  frame,
it  is  useful  to poke the background colour register before  and  after  a
specific routine to see how much of the frame it is using.

Page 70


The following will show how much of a frame it takes to clear a bitmap:

    While JoyB(0)=0
        VWait
        CLS
        move #$fOO,$dff180        ;poke background colour red
    Wend

Different  colours  can  be  used for different  parts  of  the  main  loop.
Remember that at the top of each slice the background colour will be reset.

Optimising Games

A  quality arcade game should always run to a 50th,  meaning the  main  loop
always takes less than a frame to execute and so animation etc.  are changed
every frame giving the game that smooth professional feel.

This  time  frame means the programmer will often have to sacrifice  certain
elements in the game and maybe reduce colours and size of shapes to get  the
main loop fast enough.

The following are several methods for optimising code main loops in games:

Disable Runtime Errors in the compiler options when testing speed of code as
the error checker slows code dramatically.

Poke  the  background  colour register with different  values  between  main
routines to work out which ones are taking too long:

    MainLoop:
        VWait
        Gosub movealiens
        move.w #$f00,$dff180        ;turn background red
        Gosub drawaliens
        move.w #$f00,$dff180     ;turn background green

.    Use  QBlits  if  possible  as  they are the fastest  way  of  implementing
animated graphics in Blitz2.

.    If  aliens change direction using complex routines,  split up  the  aliens
into  groups  and  every  frame  select a  different  group  to  have  their
directions changed,  the others can move in the same direction until  it  is
their  turn.  This method applies to any routines that do not have to happen
every frame but can be spread across several frames in tidy chunks.

.    Decrease the size of the display.  During a frame,  the display slows down
the  processor and blister.  A smaller display increases the amount of  time
given to the processor and blister.

There  is  an infinite number of ways to increase the speed of Blitz2  code.
subscribing  to Blitz User Magazine is one of the best ways of  speeding  up
your code!

Page 71


Those  developing  games  on machines with fast mem  and  faster  processors
should remember that most people do not have either!  It is a good  idea  to
disable fastmem when testing the speed of your code.

Page 72


10. PROGRAM EXAMPLES

Number Guessing

The  following is a small program where the computer guesses a random number
and you have to guess it in less than ten turns.

    NPrint "I just picked a number from O to 100"
    NPrint "I'll give you ten turns to guess it:"

    a=Rnd(1 00)
    n=1

    Repeat
        Print "Attempt #",n," ?"
        b=Edit(1 O)
        If b=a Then NPrint "Lucky Guess":Goto finish
        If b<a Then NPrint "Too Small"
        If b>a Then NPrint "Too Large"
        n+1
    Until n=11

    NPrint "Out of turns!"

    finish:

    NPrint "Press mouse button to exit."
    MouseWait

First  up,  you'll find it pretty hard to guess the number,  this is because
the  number  Blitz2 generates is not by default an integer  and  will  hence
include some fractional part.

Change the line a=Rnd(100) to either a.w=Rnd(100) or a=Int(Rnd(100)).

The  .w  suffix  means the variable a is now a word type  (an  integer  with
range - 32768..32767).  If you use the Int function in the second option,  a
is still a quick type but the random number has its fractional part chopped.
When  you use variables in Blitz2 without a.type suffix they default to  the
quick  type  which  is  a  number  with  range  -32768..32767  with  1/65536
accuracy.   See the Variable Types section for a more indepth discussion  of
this topic.

Page 73


If  you want all the variables in the program to default to the integer word
type, not quick then add the following line to the top of the program:

DEFTYPE .w fall variables without suffix default to words

As  with  other BASICs once the variable is used once.  it s type is defined
and future references do not require the .type suffix.

Unlike other BASICs the Print command does not move the cursor to a new line
when finished, the command NPrint is used for this.

The Edit() function is used instead of the older input command.

Also the semicolon is used instead of the REMark command in Blitz2 and  does
not retain any of it's older functionality in Print statements.

Creating a standalone Workbench program

The  number guessing program can be made to run from Workbench with its  own
icon. Add the following lines to the start of your code.

The  text  after  the semicolons are known as remarks,  as  mentioned,   the
semicolon in Blitz2 replaces the old REMark command in older BASICs.

; Number Guessing Program

WBStartup  ,necessary for prog to be run from WorkBench  FindScreen  O  ;get
front most Intuition screen ; Window 0,0,0,320,210,$1000,"Hello World",1,2

When  you compile&execute the program now,  the window replaces the  default
CLI for input and output.

One thing that you should replace is the b=Edit(10) function to:

b=Val(Edit$(10))

This gets rid of the default 0 character that appears in the window form  of
the Edit() function.

Ensure the Create Executable Icon option in the Compiler Options is  set  to
ON.

Now,   select  Create Executable from the compiler Menu or  use  the  AmigaE
keyboard shortcut.

Type the name of the program you wish to create and hit return. You have now
created your first stand alone program with Blitz2,  go to the Workbench and
click on the new program's icon to test it.

Page 74

A Graphic Example

The  following program opens its own screen and draws what  is  known  as  a
rosette,  a pattern where lines are connected between all the points  around
a circle.

;
;rosette example
;

n=20

NEWTYPE .pt
    x.w:y
End NEWTYPE

Dim p.pt(n)

For i=0 To n-1
    p(i)\x=320+Sin(2*i*Pi/n)*31 9
    p(i)\y=256+Cos(2*i*Pi/n)*255
Next

Screen 0,25 , hires 1 colour interlace screen
ScreensBitMap 0,0

For i1=0 To n-2
    For i2=i1+1 To n-1
        Line p(i1 )\x,p(i1 )\y,p(i2)\-x,p(i2)\y,1
    Next
Next

MouseWait

The  NewType .pt defined in the program has two items or fields x & y.  This
means that instead of dimming an array of x.w(n)  and y.w(n)  we can dim one
array of p.pt(n) which can hold the same information.

The  backslash "\" character is used to access the separate  fields  of  the
newtype.  The first For..Next loop assigns the points of a circle  into  the
array of points.

The  ScreensBitMap command allows us to draw directly onto the  screen  with
the Plot,  Line,  Box and Circle commands.  Programs that use windows should
not  use  this method,  rather they should draw into specific windows  using
the WPlot, WLine WBox and WCircle commands.

Page 75

Using Menus and the Blitz2 File Requester

The  following program opens its own screen & window,  attaches a menu list,
and  depending  on what the user selects from the menus,  either  opens  the
Blitz2 file requester or exits.

; A Simple File Requester example

Screen 0,11,"Select A Menu"        ;open our own intuition screen

MenuTitle O,O,"Project"            ;setup a menu list
Menultem O,O,O,O,"Load ","L"
Menultem 0,0,0,1,"Save ","S"
Menultem 0,0,0,2,"Quit ","Q"

MaxLen path$=1 92     ;MUSTbe executed before a file requester is used
MaxLen name$=192

;Set up a BACKDROP (ie - invisible) window
Window 0,0,0,320,200,$1900,"",1,2
WLocate 0,20             ;move cursor to top left of window
SetMenu 0             ;attach our menu list to our window

Repeat
    Select WaitEvent
        Case 256 fits a menu event!
            Select ItemHit

            Case 0        ;load,its item 0 which means load
            p$=FileRequest$("FileToLoad",path$, name$)
            NPrint "Attempted to Load ",p$

            Case 1         ;save fits item 1 which means save
            p$=FileRequest$(" FileToSave",path$, name$)
            NPrint "Attempted to Save ",p$

            Case 2        ;its item 2 which means quit
                End

        End Select
    End Select
Forever

The  MaxLen  command is used to allocate a certain amount of  memory  for  a
string  variable  in  Blitz2.  This is necessary  so  that  the  two  string
variables  required by the file requester command are large enough  for  the
job.

The menus created by the MenuTitle and Menultem commands are attached to the
Window using the SetMenu command.

Page 76

The  Select..Case..End  Select structures  are  the  best  way  of  handling
information  coming from a user.  When the user selects a  menu,   closes  a
window,  clicks on a gadget an 'event' is sent to your program.  Usually  an
application program will use the WaitEvent command.  which makes the program
'sleep' until the user does something.  When multitasking,  a progran1  that
is 'asleep' will not slow down the execution of other programs running.

Once  an  event is received,  the event code returned by WaitEvent specifies
what  type  of an event occurred.  A menu event returns 256 ($100  hex),   a
close window event returns 512 ($200 hex).  A full list of events and  their
IDCMP codes is listed on page 25-5 of the Blitz2 reference manual.

String Gadgets

The  following program demonstrates the use of string gadgets.  These  allow
the  user  to enter text via the keyboard.  The following sets up  3  string
gadgets for decimal, hex and binary input/output.

When  the user types a number into one of the gadgets and hits return,   the
program  receives  a gadgetup event.  The GadgetHit function  returns  which
gadget  caused  the event.  The program then converts the  number  the  user
typed  into the other number systems (decimal,  hex or binary)  and displays
the results in each of the string gadgets.

The  ActivateString command means the user does not need  to  click  on  the
gadget to reactivate it so that they can type in another number.

;
;decimal hex binary converter
;

FindScreen O

StringGadget 0,64,12,O,O,18,144
StringGadget O,64,26,O,1,18,144
StringGadget O,64,4O,O,2,18,144

Window O,10O,5O,22O,56,$1008,"BASE CONVERTER",1,2,0

WLocate 2,04:Print "DECIMAL"
WLocate 2,18:Print " HEX$"
WLocate 2,32:Print "BINARY%"

DEFTYPE.I value

Repeat
    ev.l=WaitEvent
    If ev=$40         ;gadget up

        Select GadgetHit
            Case O
                value=Val(StringText$(O,O))
            Case 1

Page 77



                r$=UCase$(StringText$(0,1))
                value=O:i=Len(r$):b=1
                While i>0
                    a=Asc(Mid$(r$,i,1))
                    If a>65 Then a-55 Else a-48
                    value+a*b
                    i-1 :b*16
                Wend
            Case 2
                r$=StringText$(0,2)
                value=O:i=Len(r$) b=1
                While i>0
                    a=Asc(Mid$(r$,i,1))-48
                    value+a*b i-1
                    :b*2
                Wend
            End Select
            ActivateString 0,GadgetHit
            SetString O,O,Str$(value)
            SetString 0,1,Right$(Hex$(value),4)
            SetString 0,2,Right$(Bin$(value),16)
            Redraw O.O:Redraw 0.1 Redraw 0 2
            Endif
Until ev=$200

Prop Gadgets

The following program creates a simple RGB palette requester,  allowing  the
user to adjust the colors of the screen.  PropGadgets can be thought  of  as
sliders,  in this example we create three vertical PropGadgets to  represent
the Red, Green and Blue components of the current color register selected.

The  32  color registers are represented with 32 text gadgets.  The gadget's
colour  is  set  by changing GadgetPens before the gadget is  added  to  the
gadget  list.   Using GadgetJam I the two spaces are shown  as  a  block  of
colour.

;
; simple palette requester
;

FindScreen O

For p=O To 2
    PropGadget 0,p*22+8,14,128,p,16,54
Next

For c=O To 31 GadgetJam 1 :GadgetPens O,c
    x=c AND 7:y=lnt(c/8)
    TextGadget 0,x*28+72,14+y*14,32,3+c," " ;<-2 spaces
Next

Page 78

Window 0,100,50,300,72,$100A,"PALETTE REQUESTER",1,2,0

cc=0:Toggle 0,3+cc,0n:Redraw 0,3+cc

Repeat
    SetVProp 0,0,1-Red(cc)/15,1/16
    SetVProp 0,1,1 -Green(cc)/15,1/16
    SetVProp 0,2,1 -Blue(cc)/15,1/16
    Redraw 0,0:Redraw 0,1 :Redraw 0,2
    ev. l=WaitEvent
    If ev=$40 AND GadgetHit>2
        Toggle 0,3+cc,0n:Redraw 0,3+cc
        cc=GadgetHit-3
        Toggle 0,3+cc,0n:Redraw 0,3+cc
    Endif
    If (ev=$20 OR ev=$40) AND GadgetHit<3
        r.b=VPropPot(0,0)*16
        g.b=VPropPot(0,1)*16
        b.b=VPropPot(0,2)*16
        RGB cc,15-r,15-g,15-b
    Endif
Until ev=$200

Database Type Application

The  following  listing is a simple data base program  to  hold  a  list  of
names, phone numbers and addresses.

The  user  interface can either be typed in as listed or created  using  the
IntuiTools tutorial later in this manual.

If  a  text file exists called phonebook.data we read it into a list,   each
item of the list has been set up to hold 4 strings using the NewType person.
Using  a  list instead of a normal array means that we think of each  record
inside  the  list  as connected to the one before and the one  after  rather
than just being an individual item.  Blitz2 keeps an internal pointer to the
'current'  item  and  the various list commands enable  us  to  change  that
internal pointer and operate on the item it points to.

Dhone book program

FindScreen 0

;the following is from ram:t as created in the intuitools tutorial

Borders On:BorderPens 1,2:Borders 4,2
StringGadget 0,72,12,0,1,40,239

Page 79


StringGadget 0,72,27,0,2,40,239
StringGadget 0,72,43,0,3,40,239
StringGadget 0,72,59,0,4,40,239
GadgetJam 0:GadgetPens 1,0
TextGadget 0,8,75,0,10,"NEW ENTRY"
TextGadget 0,97,75,0,11,-I <"
TextGadget 0,129,75,0,12, "<<"
TextGadget 0,161,75,0,13, ">>"
TextGadget 0,193,75,0,14,">1 "
TextGadget 0,226,75,0,15,"DIAL"
TextGadget 0,270,75,0,16,"LABEL"

SizeLimits 32,32,-1,-1
Window 0,0,24,331,91,$100E,"MY PHONE BOOK",1,2,0
WLocate 2,19:WJam 0:WColour 1,0
Print "Address"
WLocate 19,50
Print "Phone"
WLocate 27,3
Print "Name"

; and now we start typing...

#num=4 ;4 strings for each person

NEWTYPE .person
info$[#num]
End NEWTYPE

Dim List people.person(200)

USEPATH people()

; read in names etc from sequential file

If ReadFile (0 , "phonebook. data")
    Filelnput 0
    While NOT Eof(0)
        If Additem(people())
            For i=0 To #num-1 :\info[i]=Edit$(128):Next
        Endif
    Wend
Endif

ResetList people()

;if empty add blank record

If NOT Nextitem(people()) Then Additem people()

refresh:

Page 80


ref=0
For i=0 To #num-1
    SetString 0,i+1,\info[i]:Redraw 0,i+1
Next
ActivateString 0,1 :VWait 5
Repeat
    ev.l=WaitEvent
    ;
    if ev=$200            ;close window event
    Gosub update
    If WriteFile (0,"phonebook.data");save data to file
    FileOutput 0
    ResetList people()
    While Nextitem(people())
        For i=0 To #num-1 :NPrint \info[i]:Next
    Wend
    CloseFile 0
Endif
Endif

If ev=64
If GadgetHit=#num Then ActivateString 0,1
If GadgetHit<#num Then ActivateString 0,GadgetHit+1
    Select GadgetHit
        Case 1 0
            Gosub update:lf Additem(people()) Then ref=1
        Case 1 1
            Gosub update:lf Firstitem(people()) Then ref=1
        Case 1 2
            Gosub update:lf Previtem(people()) Then ref=1
        Case 1 3
            Gosub update:lf Nextitem(people()) Then ref=1
        Case 1 4
            Gosub update:lf Lastitem(people()) Then ref=1
        End Select
Endif
Until ref=1
Goto refresh

Update:
For i=0 To #num-1:\info[i]=StringText$(0,i+1) : Next: Return

Page 81


List Processor for Exec based Lists

The  Following  program  is  an   example   of  accessing  Operating  System
structures.   Before  entering  this  program  you  will  need  to  add  the
AmigaLibs.res file to the Blitz 2 environment.  To do this open the Compiler
Options  requester from the Compiler Menu.  Click in the Residents  box  and
type in AmigaLibs.Res.

You  may  need a pathname.  AmigaLibs is found in the Resident directory  of
the Blitz 2 program disk.

By  selecting  ViewTypes from the compiler menu the entire  set  of  structs
should be listed that are used by the Amiga's operating system.

The  first  line of our program defines the variable exec as  a  pointer  to
type  ExecBase.  As the Amiga keeps the location of this variable in  memory
location  4 we can use the Peek.l (long)  command to read the 4  byte  value
from memory into our pointer vanable.

Blitz  2  now knows that exec points to an execbase structure and using  the
backslash  character we can access any of the variables in this stucture  by
name.

If  you  select ViewTypes from the compiler menu and type in ExecBase  (case
sensitive) you can view all the variables in the execbase structure.

We  then  define another pointer type called *mylist.List.  We can then  use
this to point to any List found in execbase such as LibList or DeviceList.

An  exec list consists of a header node and a series of link nodes that hold
the list of devices or libraries or what have you.

We point mynode at the lists first link node in the third line of code.

The  next  line  loops  through the link nodes until the node's  successor=0
which means we have arrived back at the header node.

Peek$  reads  ascii data from memory until a zero is found,   this  is  very
useful  for  placing text pointed to by a C definition  such  as  *In_Name.b
into Blitz 2's string work area.

We then point mynode at the next node in the list.

Exec /ist processor

*exec.ExecBase=Peek.1(4)

*mylist.List=*exec\LibList

*mynode.Node=*mylist\lh_Head

While *mynode\ln_Succ


Page 82


a$=Peek$(*mynode\1n_Name)
NPrint a$
Amynode=*mynode\ln Succ
Wend

MouseWait

Prime Number Generator

The following program generates a list of prime numbers from 2 up to a limit
specified by the user.  A list of all the prime numbers found is kept  in  a
Blitz 2 List structure.

We  begin by inputting the upper limit from the user using the default input
output and the edit() command, the numeric form of the edit$() command.

The  While..Wend structure is used to loop through the main algorithm  until
the  upper  limit is reached.  The algorithm simply takes the next  integer,
loops  through the list of the prime numbers it has already generated  until
either  it finds a divisible number or it is too far through the  list  (the
item  in  the  list  is  greater than the square root of  the  number  being
checked).

If  the algorithm does not find a divisor in its search through the list  it
prints the new prime and adds it to the end of the list.

Print "Primes to what value "    ;find out limit to run program to
v=Edit(80)            ;input numeric
If v=0 Then End            ;if O then don't carry on
tab.w=0:tot.w=0            ; reset counters
Dim List primes(v)        ; dim a list to hold primes
p=2                ;add the number2 to ourlist
Additem primes()
primes()=p

While p<v        ;loop until limit reached
p+1            ;increment p
flag=1            ;set flag
d=0
q=Sqr(p)         ; set search limit
ResetList primes()    ;loop through list
While Nextitem(primes()) AND d<q AND flag
d=primes()
flag=p MOD d
Wend
If flag<>0             ;if found print and add it to list
    Print p,Chr$(9)     ;chr$(9) is a TAB character
    tab+1 :tot+1
    If tab=10 Then NPrint "":tab=0
    AddLast primes()
    primes()=p
Endif

Page 83


Wend

NPrint Chr$(10)+"Found ",tot," Primes between 2 & ",v
NPrint "Left Mouse Button to Exit"

MouseWait

Clipped Blits

The  following program illustrates a method to clip bliss.  When a shape  is
blitted outside the area of a bitmap an error occurs.  To have shapes appear
half  inside  a bitmap and half outside we use a larger bitmap and  position
the display inside.  The size of the outer frame is dependent on the size of
the shapes that will be drawn.

In  the  following example we are using 32x32 pixel shape  and  so  need  an
extra  32 pixels all round the bitmap.  The Show 0,32,32 centres the display
inside the larger bitmap.

We  also  have  to  use the extended form of the slice  command  as  we  are
displaying a bitmap wider than the display.

The  RectsHit(x,y,  I,  1,0,0,320+32,256+32)  function returns true  if  the
shape  is inside the larger bitmap and should be blitted.  If the shape  was
larger  or  it had a centred handle the parameters would need to be  changed
to accomadate these factors.

The.makeshape routine creates a temporary bitmap to draw a patern  and  then
transfer it to a shape object using the GetaShape command.

BLITZ

Gosub makeshape

BitMap 0,320+64,256+64,3
Slice 0,44,320,256,$fff8,3,8,8,320+64,320+64
Show 0,32,32

While Joyb(O)=0
x.w=Rnd(1024)-512
y.w=Rnd(1024)-512
If RectsHit(x,y,1,1,0,0,320+32,256+32)
Blit O,x,y
Endif
Wend

.makeshape:
BitMap 1,32,32,3
For i=1 To 15:Circle 16,16,i,i:Next
GetaShape 0,0,0,32,32
Free BitMap 1
Return

Page 84


Dual Playlield Slice

The  following program demonstrate the use of a dual playfield display.   As
described  in  the  previous  chapter dual playfield  lets  us  display  two
bitmaps simultaneously using the ShowF and ShowB commands.

The macro rndpt simply inserts the code Rnd((i40),Rnd(5 12)  into the source
each time it is called.  For instance Line !rndpt,!rndpt,Rnd(7)  is expanded
internally by the compiler to reud:

Line Rnd(640),Rnd(512),Rnd(640),Rnd(512),Rnd(7)

Once  again the extended from of the slice command has to be used with flags
set to $fffa giving us a lores dualplayfield scrollable display.

In  dualplayfield  we can think of having two displays,  the  ShowF  command
positions  the  front display inside BitMap 1,  the ShowB command  positions
the backdrop display inside BitMap 0.  Note that we must pass the x position
of  the  other  display  with ShowF and ShowB so that Blitz2  can  calculate
internal variables properly.

BLITZ

Macro rndpt Rnd(640),Rnd(512):End Macro

BitMap 0,640,512,3
For i=0 To 255
    Line !rndpt,!rndpt,Rnd(7)
Next

BitMap 1,640,512,3
For i=0 To 255
    Circlef!rndpt,Rnd(15),Rnd(7)
Next

Slice 0,44,320,256,$fffa,6,8,16,640,640

While Joyb(O)=0
VWait
x1 =160+Sin(r)* 160
y1 =128+Cos(r)*128
x2=160-Sin(r)*160
y2=128-Cos(r)4128
ShowF 1,x1,y1,x2
ShowB 0,x2,y2,x1
r+.O5
Wend

Page 85


Double Buffering

The  following  code  illustrates the use  of  a  double  buffered  display,
necessary  to  acheive  smooth  moving  graphics.   The  trick  with  double
buffering  is  that while one bitmap is displayed we can  change  the  other
without any glitches happening on the display.

The  VWait  command waits for the vertical beam to be  at  the  top  of  the
display,   which is when we are allowed to swap the bitmaps being  displayed
without getting any glitches.

The  db=l-db equation will mean that db alternates between O & 1 each frame.
We  Show  db,  toggle it (db=l-db)  and then Use Bitmap db,  to acheive  the
"draw  to  one bitmap while displaying the other" technique known as  double
buffering.

Because  we  have  two bitmaps,  we need two queues to use  QBlit  properly.
QBlits work by doing a normal Blit and storing the position of the  Blit  in
a  queue.  The UnQueue command will erase all parts of the screen listed  in
the  queue  so  we can draw the balls in their new positions with  out  them
leaving "trails" behind them from their old position.

The move #-1,$dffl80 pokes the background color to white,  this allows us to
see  how  much  of the frame has been taken since the VWait to  execute  the
code.  If we increase the number of balls,  the moving and drawing loop will
take  longer  than  a  frame (50th of a second)  and the  white  will  start
flashing as the poke will only be happening every second frame.  See chapter
10 for a more thorough discussion of frame rates etc.

Hmm,   the only other thing I'll mention is the bounce logic used  when  the
ball  moves outside the bitmap.  We reverse the direction but also  add  the
new  direction  to the position so the program never attempts  to  Blit  the
shape outside of the bitmap.

BLITZ

n=25

NEWTYPE .ball
    x.w:y:xa:ya
End NEWTYPE

Dim List b.ball(n-1)
While Additem(b())
    b()\x=Rnd(320-32), Rnd (256-32), Rnd (4)-2, Rnd(4)-2
Wend

Gosub getshape

BitMap 0,320,256,3
BitMap 1,320,256,3
Queue O,n
Queue 1,n
Slice 0,44,3

Page 86


While Joyb(0)=0
VWait
Show db
db=1-db
Use BitMap db
UnQueue db
ResetList b()
USEPATH b()
While Nextitem(b())
    \x+\xa:\y+\ya
    If NOT RectsHit(\x,\y,1,1,0,0,320-32,256-32)
    \xa=-\xa:\ya=-\ya
    \x+\xa:\y+\ya
Endif
QBlit db,0,\x,\y

Wend
MOVE #-1,$dff180
Wend

End

.getshape:
BitMap 1,32,32,3
For i=1 To 15:Circle 16,16,i,i:Next
GetaShape 0,0,0,32,32
Free BitMap 1
Return

Smooth Scrolling

This  final  example  demonstrates smooth  scrolling  as  discussed  in  the
previous chapter.

The  Scroll  commands are used to copy the left side of the  bitmap  to  the
right  and  the top half of the bitmap to the bottom.  This in effect  means
the large bitmap is the same in each quarter.

Because  of this we can scroll the display across the bitmap,  and  when  we
hit  the right edge reset the display back to the left edge without any jump
in  the  display as both left and right sides of the bitmap  are  the  same.
This is the same for scrolling the display down the bitmap.

Note how to be able to access mouse moves we need the Mouse On command.   We
can then take the amount the mouse has been moved by the user and add it  to
the speed in which we are moving the display around the bitmap.

The  QLimit(xa+MouseXSpeed,-2O,20)  command makes sure that the  xa  (x_add)
variable always stays inside the limits -20..20.

The x=QWrap(x+xa,O,320) command means that when the displays position inside

Page 87


the bitmap reached the right edge of the bitmap it wraps around to the left.

BLITZ
Mouse On
n=25
BitMap 0,640,512,3

For i=0 To 150
    Circlef Rnd(320-32)+16,Rnd(256-32)+16,Rnd(16),Rnd(8)
Next

Scroll 0,0,320,256,320,0
Scroll 0,0,640,256,0,256

Slice 0,44,320,256,$fff8,3,8,8,640,640

While Joyb(0)=0
VWait
Show db,x,y
xa=QLimit(xa+MouseXSpeed,-20,20)
ya=QLimit(ya+MouseYSpeed, -20,20)
x=QWrap(x+xa,0,320)
y=QWrap(y+ya,0,256)
Wend

Page 88



11. DISPLAY LIBRARY & AGA PROGRAMMING

Introduction
The  Display  Library  is  a  recent addition  to  Blitz.   Developed  as  a
replacement to Slices it not only offers games programmers access to all  of
the  new  AGA  features  but  offers a slightly  more  modular  approach  to
controlling the Amiga's graphics hardware.

The  Amiga's display is controlled by the copper.  The copper is a secondary
processor that executes a list of instructions every frame.  For  those  new
to  such  concepts,  the Amiga redraws the screen 50 times a  second,   each
redraw  is known as a frame.  The video beam which sweeps across the  screen
drawing  each  pixel  is  controlled by certain hardware  registers,   these
registers are poked by the copper whose job it is to keep everything m sync.
A  coplist  contains  information about the colours,   bitplanes,   sprites,
resolution  and  more  that  the video beam requires  to  render  a  typical
display.

Initialising

Unlike  Slices  which  appear as soon as they are  initialised  the  display
library requires coplists to be initialised (using InitCopList)  prior to  a
display being created (using CreateDisplay).  The important difference  here
is  that  Slices require memory to be allocated each time a  change  to  the
video  display  is  required  while  the  Display  library  allows  multiple
CopLists to be initialised before any displays are created.

There  are  two forms of the InitCopList command.  The short version  simply
requires the CopList# which is to be initialised and the flags.  The  height
of the display will default to 256 pixels high.  A width of 320, 640 or 1280
will  be  used  depending on the resolution set in the  flags  as  will  the
number of colors.

The longer version has the following format:

InitCopList CopList#,ypos,height, type,sprites,colors,customs

The  ypos  is usually set to 44 the standard top of frame for a PAL display.
If  the CopLIst is to be used below another coplist on the same display ypos
should be set to 2 scan lines below the last CopLists bottom line.

Sprites  should always be set to eight,  even if they are not all available,
colors  should  be  set to the number required.  When  using  more  than  32
colours ensure that the #agacolors flag MUST be set.

Customs  allocate  enough  room  for advanced  custom  copper  lists  to  be
attached to each display.  See later on in this chapter for a discussion  on
using customcops.

Page 89

Flags used with InitCopList

The flags value is calculated by adding the following values together.

Note:  variables must be long (32 bits) when used as the flags parameter for
the InitCoplist command.

#onebitplane=                $01
#twobitplanes=                $02
#threebitDlanes=            $03
#fourbitplanes=                $04
#fivebitplanes=                $05
#sixbitplanes=                $06
#sevenbitplanes=            $07*
#eightbitplanes=            $08*

#smoothscrolling=    $10    ;set if you will be scrolling the bitmap
#dualplavfield=        $20    ;enable dual playfield mode
#extrahalfbrite=    $40    ;forces 6 bitplane display into ehb mode
#ham=            $80    ;display in ham

#lores=                    $000
#hires=                    $100
#superhires=                $200

#loressprites=                $400
#hiressprites=                $800*
#superhiressprites=            $c00

#fetchmodeO=                $0000
#fetchmode1 =                $1000*
#fetchmode2=                $2000*
#fetchmode3=                $3000*

#agacolors=                    $10000*

* These flags should only be used with AGA Amigas.

Colors

The #agacolors flag must ALWAYS be set when more than 32 colours are in  use
or when 24 bit color definition is required.

SmoothScrolling

By  setting the smooth scrolling flag the extended form of DisplayBitmap may
be used which allows the bitmap to be displayed at any offset.  This enables
the  programmer  to scroll the portion of the bitmap being  displayed.   See
BlitzMode programming chapter for an explanation of hardware scrolling.

Notes:

*  Always  use the extended form of DisplayBitmap with smoothscrolling  set,
even when offset is 0,0.

Page 90


*  DisplayBitmap accepts quick types for the x offset and will position  the
bitmap in fractions of pixels on AGA machines.

*  The width of the display will be less than the default 32()/640/1280 when
smooth scrolling is enabled.

DualPlayfield

By  setting the DualPlayfield flag two bitmaps may be displayed  on  top  of
each  other  in  one   display.    A   combination   of   DualPlayfield  and
SmoothScrolling is allowed for parallax type effects.  Note  that  with  AGA
machines,   it  is  possible to display two 16 colour  bitmaps  by  enabling
DualPlayfield and setting number of bitmaps to 8.

Sprites

The  number of sprites available will depend on the type of display and  the
fetchmode  settings Most AGA modes will require the  display  to  be  shrunk
horizontally  for 8 sprites to be displayed.  Currently  this  can  only  be
acheived using the DisplayAdjust command,  certain examples of this  can  be
found on the Blitz examples disk.

AGA  hardware allows the programmer to display sprites in lores,   hires  or
superhires.  The higher resolutions allow graphics dithering by the  artist,
essential  if  3  coloured  sprites are in use.   Larger  sprites  are  also
available  using  the  SpriteMode command.  Dithered  large,   super  hi-res
sprites  can  be  created  to  look better than lower  resolution  16  color
sprites using such tools as ADPro.

Note  that it is unrealistic to display more than 4 bitplanes and have  more
than  3  sprite channels available,  the adjust required results in  a  very
narrow display indeed.

FetchMode

AGA  hardware allows bitplane data to be fetched by the DMA in 16,32  or  64
pixel groups.  The larger fetches give the processor more bandwidth, this is
especially noticeable with AGA Amiga's running without additional fastmem.

When  using increased fetchmodes bitplanes must always be a multiple  of  64
pixels wide.

Those  wanting to attempt DisplayAdjusts on displays with larger  fetchmodes
will  encounter severe difficulties in creating a proper display.  We  think
it  is actually impossible for displays to run at fetchmode 3 with more than
I sprite without having to adjust the display to around 256 pixels across.

Multiple Displays

When  more than one CopList is to be displayed care must be taken that there
is  a  gap of at least 3 lines between each.  This means the ypos of a lower
coplist must be equal or greater than the above's ypos+height+3.

Page 91

Advanced Copper Control

The  long  format  of the InitCopList command allows allocation  for  custom
copper  commands.  Certain commands have been added to the  Display  Library
which will require this parameter to be set.

There  are  two forms of custom copper commands,  the first will  allow  the
copper  to  affect  the display every scanline while the  second  defines  a
certain line for the copper to do it's thing. These new commands include:

The  following  require  a  negative   size,   this  denotes  that  so  many
instructions must be allocated for every scanline of the display.

DisplayDblScan      CopList#,Mode[,copoffset];(size=-2)       DisplayRainbow
CopList#,Register,Palette[,copoffset]   ,(ecs=-   I   aga=-4)     DisplayRGB
CopList#,Register,line,r,g,b[,copoffset]   ;(ecs=-1   aga=-4)    DisplayUser
CopList#,Line,String[,CopOffset];(size=-len/4)                 DisplayScroll
CopList#,&xpos.q(n),&xpos.q(n)[,CopOffset];(size=-3)

The  following  require  the  size  be specified  as  a  positive  parameter
denoting  that so many instructions be allocated for each instance  of  each
command.   Note that these two commands may NOT be mixed with  the  commands
above.

CustomColors   CopList#,CCOffset,YPos,Palette,startcol,numcols  CustomString
CopList#,CCOffset, YPos,Copper$

The  use  of  these commands is illustrated by code included  in  the  Blitz
examples drawer.

Page 92

Display Example 1

This  first example creates two large bitmaps.  It renders lines to one  and
boxes  on the other.  A 32 color palette is created the first 16 colors  are
used by the back playfield and second 16 by thr front piayfield.

The flags in the InitCopList command are the sum of the following:

    #eightbitplanes=    $08
    #smoothscrolling=    $10
    #dualplayfield=        $20
    #lores=            $000
    #fetchmode3=        $3000*
    #agacolors=        $10000*

Note  how  the InitCopList command can be executed before going  into  Blitz
mode.   All  the  display   commands   are   mode   independent  except  for
CreateDisplay which can only be executed in Blitz mode.

Finally  note the extended form of the DispiayBitmaD command.   This  allows
the offset position of both bitmaps to be assigned with the one command.

;
; two 16 color playfield in dualplayfield mode
;
BitMap 0,640,512,4
BitMap 1,640,512,4

For i=0 To 100
    Use BitMap O:Box Rnd(640) Rnd(512) Rnd(640) Rnd(512) Rnd(16)
    Use BitMap 1:Line Rnd(640j,Rnd(512j,Rnd(640j,Rnd(512j,Rnd(16)
Next

InitPalette 0 32
For i=1 To Si :AGAPalRGB 0,i,Rnd(256),Rnd(256),Rnd(256):Next

InitCopList 0,$13038

BLITZ

CreateDisplay O
DisplayPalette 0,0

While Joyb(O)=0
    VWait
    x=160+Sin(r)*160:y=128+Cos(r)*128
    DisplayBitMap 0,O,x,y,1,320-x,256-y
    r+.O5
Wend

End

Page 93


Display Example 2

This  second  example demonstrates the use of sprites  on  a  Display.   The
DisplayAdjust  is  required  so as to  allow  us  access  to  all  8  sprite
channels.   Unfortunately it is difficult to  up  the  fetch  mode  in  this
example without resorting to a very thin display.

The  SpriteMode2  tells  Blitz to create 64  pixel  wide  sprites  for  each
channel.   With  out  the SpriteMode each sprite would require  4  channels,
again this is one of the better new features of AGA.

It  should  be  noted  also  that  the DisplaySprite  command  also  accepts
fractional  x  parameters and will position the sprite at  fractional  pixel
positions if possible.

;
; smoothscrolling 16 color screen with 8 64 wide sprites
;
SpriteMode 2
InitShape 0,64,64,2:ShapesBitMap O,O
Circlef 32,32,32,1 :Circle7 16,8,6,2:Circlef 48,8,6,3:Circlef 32,32,8,0
GetaSprite 0,0

BitMap 0,640,512,4

For i=0 To 100
    Use BitMap O:Box Rnd(640),Rnd(512),Rnd(640),Rnd(512),Rnd(16)
Next

InitPalette 0,48

For i=1 To 31 :AGAPalRGB 0,i,Rnd(256),Rnd(256),Rnd(256):Next

InitCopList 0,$10014

DisplayAdjust 0, -2,8,0,16,0; under scan!

BLITZ

CreateDisplay O
DisplayPalette 0,0

For i=0 To 7
    DisplaySprite 0,0,20+i*30,(20+i*50)&127,i
Next

While Joyb(O)=0
    VWait
    x=160+Sin(r)*160:y=128+Cos(r)*128
    DisplayBitMap O,O,x,y
    r+.O5
Wend

End

Page 94


R-1: PROGRAM FLOW COMMANDS

A  computer  program is made up of a sequence of commands that are  executed
sequentially (one after the other).  Certain commands are used to  interrupt
this process and cause program execution to jump to a different location  in
the  program.  There are several different ways of controlling this  program
flow in Blitz.

Standard  BASIC  commands to change program flow such as  Goto,   Gosub  are
standard in Blitz,  unlike older BASIC's, locations are specified as program
labels and not line numbers.  More modern structured BASIC features such  as
Procedures (known as Statements and Functions),  While..Wend, Repeat..Until,
Select..Case and more allow a more structured approach to programming.

Finally  Blitz allows control over Interrupts,  this allows external  events
to  override  normal program flow and jump (temporarily)   to  a  predefined
location in the program.

Goto Program Label

Goto  causes program flow to be transferred to the specified program  label.
This allows sections of a program to be 'skipped' or 'repeated'.

Gosub Program Label

Gosub  operates  in  two  steps.  First,  the location  of  the  instruction
following  the Gosub is remembered in a special storage area (known  as  the
'stack').   Secondly,  program flow is transferred to the specified  Program
Label.

The  section of program that program flow is transferred to is  known  as  a
'subroutine' and should be terminated by a Return command.

Return

Return  is  used  to  return program flow to the instruction  following  the
previously  executed   Gosub   command.    This   allows   the  creation  of
'subroutines' which may be called from various points in a program.

On Expression Goto| Gosub Program LabelLProgram Label...]

On  allows a program to branch,  via either a Goto or a Gosub,  to one of  a
number  of  Program  Labels  depending upon  the  result  of  the  specified
Expression.

If  the  specified Expression results in a 1,  then the first Program  Label
will  be branched to.  A result of 2 will cause the second Program Label  to
be branched to and so on.  If the result of Expression is less than one,  or
not enough

Program Labels are supplied, program flow will continue without a branch.

End

End will halt program flow completely.  In the case of programs run from the
Blitz editor,  you will be returned to the editor. In the case of executable
files, you will be returned to the Workbench or CLI.

PAge 95

Stop

The Stop command causes the Blitz Debugger to interrupt program flow.  Place
Stop  commands  in your code as breakpoints when debugging,  ensure  runtime
errors are enabled.  Click on Run from the debugger to continue program flow
after a Stop.

If Expression [Then...]

If  allows execution of a section of program depending on the result  of  an
expression.  The Then command indicates only the rest of the  line  will  be
defined as the section of code to either execute or not.  Without a Then the
section of code will be defined as that up to the EndIf command.

Endif

EndIf  is used to terminate an 'If block'.  An If block is begun by  use  of
the  If  statement without the Then present.  Please refer to  If  for  more
information on If blocks.

Else [Statement..]

Else  may  be used after an If to cause program instructions to be  executed
if the expression specified in the If proved to be false.

While Expression

The  While command is used to execute a series of commands repeatedly  while
the  specified Expression proves to be true.  The cAmmands  to  be  executed
include all the commands following the While until the next matching Wend.

Wend

Wend is used in conjunction with While to determine a section of program  to
be executed repeatedly based upon the truth of an expression.

Select Expression

Select examines and 'remembers' the result of the specified Expression.  The
Case  commands  may  then be used to execute different sections  of  program
code depending on the result of the expression in the Select line.

Case Expression

A Case is used following a Select to execute a section of program code when,
and only when,  the Expression specified in the Case statement is equivalent
to the Expression evaluated in the Select statement.

If a Case statement is satisfied,  program flow will continue until the next
Case Default or End Select statement is encountered,  at which point program
flow will branch to the next matching End Select.

Page 96

Default

A  Default  statement may appear following a series of  Case  statements  to
cause  a  section  of  program  code to be executed  if  NONE  of  the  Case
statements were satisfied.

End Select

End  Select  terminates a Select...Case...Case...Case sequence.  If  program
flow  had been diverted through the use of a Case or Default statement,   it
will continue from the terminating End Select.

For Var=Expression 1 To Expression2 [Step Expression3]

The  For  statement initializes a For...Next loop.  All For/Next loops  must
begin  with  a  For statement,  and must have a terminating  Next  statement
further  down  the program.  For..Next loops cause a particular  section  of
code to be repeated a certain number of times.  The For statement does  most
of  the  work  in  a  For/Next  loop.  When For is executed,   the  variable
specified  by Var (known as the index variable)  will be set  to  the  value
Expressionl. After this, the actual loop commences.

At the beginning of the loop, a check is made to see if the value of Var has
exceeded  Expression2.   If so,  program flow will  branch  to  the  command
following the For/Next loop's Next,  ending the loop.  If not,  program flow
continues  on until the loop's Next is reached.  At this point,   the  value
specified  in Expression3 (the 'step' value)  is added to Var,  and  program
flow  is  sent  back  to the top of the loop,  where Var  is  again  checked
against Expression2.  If Expression3 is omitted,  a default step value of  I
will be used.

In  order  for  a For/Next loop to count 'down' from one value  to  a  lower
value, a negative step number must be supplied.

Next [var[,Var..]]

Next terminates a For..Next loop.  Please refer to the For command for  more
information on For..Next loops.

Repeat

Repeat is used to begin a Repeat...Until loop.  Each Repeat statement  in  a
program must have a corresponding Until further down the program.

The  purpose  of  Repeat/Until loops is to cause a section  of  code  to  be
executed  AT LEAST ONCE before a test is made to see if the code  should  be
executed again.

Until Expression

Until is used to terminate a Repeat/Until loop.  If Expression proves to  be
true  (non  0),  then program flow will continue from the command  following
Until.  If Expression proves to be false (0), then program flow will go back
to the corresponding Repeat, found further up the program.

Page 97

Forever

Forever may be used instead of Until to cause a Repeat/Until loop  to  NEVER
exit. Executing Forever is identical to executing 'Until 0'.

Pop Gosub| For| Select| If| While| Repeat

Sometimes,   it may be necessary to exit from a particular type  of  program
loop  in  order to transfer program flow to a different part of the program.
Pop  must be included before the Goto which transfers program flow out  from
the inside of the loop.

Actually,  Pop is only necessary to prematurely terminate Gosubs,  Fors  and
Selects.  If,  While and Repeat have been included for completeness but  are
not necessary.

MouseWait

MouseWait simply halts program flow until the left mouse button  is  pushed.
If  the left mouse button is already held down when a MouseWait is executed,
program flow will simply continue through.

MouseWait  should  normally be used only for program testing  purposes,   as
MouseWait severely slows down multi-tasking.

VWait [Frames]

VWait  will cause program flow to halt until the next vertical blank occurs.
The optional Frames parameter may be used to wait for a particular number of
vertical blanks.

VWait  is  especially useful in animation for synchrodizing display  changes
with the rate at which the display is physically redrawn by the monitor.

Statement Procedurename{[ParameterltParamater2...]]}

Statement declares all following code up to the next End Statement as  being
a 'statement type' procedure.

Up  to  6  Parameters  may be passed to a statement in  the  form  of  local
variables through which calling parameters are passed.

In  Blitz,   all statements and functions must be declared before  they  are
called.

End Statement

End  Statement declares the end of a 'statement type' procedure  definition.
All statement type procedures must be terminated with an End Statement.

Statement Return

Statement  Return  may be used to prematurely exit from a  'statement  type'
procedure.  Program flow will return to the command following the  procedure
call.

Page 98

Function [. Type] Procedurename{[Parameterl[,Parameter2...]]}

Function declares all following code up to the next End Function as being  a
function  type  procedure.   The optional Type  parameter  may  be  used  to
determine  what  type  of  result is returned by the  function.   Type.   if
specified,  must be one Blitz's 6 primitive variable types.  If no  Type  is
given, the current default type is used.

Up  to  6  Parameters  may be passed to a function  in  the  form  of  local
variables through which calling parameters are passed.  Functions may return
values through the Function Return command.

In  Blitz,   all statements and functions must be declared before  they  are
called.

End Function

End Function declares the end of a 'function type' procedure definition. All
function type procedures must be terminated with an End Function.

Function Return Expression

Function Return allows 'function type' procedures to return values to  their
calling expressions.  Function type procedures are always called from within
Blitz expressions.

Shared Var[,Var...]

Shared is used to declare certain variables within a procedure definition as
being  global  variables.   Any   variables  appearing  within  a  procedure
definition that do n<>t appear in a Shared statement are,  by default, local
variables.

Setint Type

Setint  is  used  to declare a section of program code as 'interrupt'  code.
Often,   when  a  computer program is running,  an event of some  importance
takes  place  which must be processed immediately.  The different  types  of
interrupt on the Amiga are as follows:

Type        Cause of Interupt

()        Serial transmit buffer empty
1        Disk Block read/written
2        Sottware interupt
3        Cia ports interupt
4        Co-processor ('copper') interupt
5        Vetical Blank
6        glitter finished
7        Audio channel 0 pointer/length fetched
8        Audio channel I pointer/length fetched
9        Audio channel 2 pointer/length fetched
10        Audio channel 3 pointer/length fetched
11        Serial receive butffer full
12        Floppy disk sync
13        External interupt

Page 99



The  most useful of these interrupts is the vertical blank interrupt.   This
interrupt  occurs every time an entire video frame has been fully  displayed
(about  every  sixtieth  of  a second),  and is very  useful  for  animation
purposes.   If a section of program code has been designated as  a  vertical
blank  interrupt handler,  then that section of code will be executed  every
sixtieth of a second.

Interrupt  handlers  must  perform   their  task  as  quickly  as  possible,
especially  in  the case of vertical blank handlers which  must  NEVER  take
longer than one sixtieth of a second to execute.

Interupt  handlers  in Blitz must NEVER access string variables  or  literal
strings.  In Blitz mode, this is the only restriction on interrupt handlers.
In Amiga mode, no blister, Intuition or file i/o commands may be executed by
interrupt handlers.

To set up a section of code to be used as an interrupt handler,  you use the
SetInt command followed by the actual interrupt handler code.  An End SetInt
should follow the interrupt code.  The Type parameter specifies the type  of
interrupt,  from the above table,  the interrupt handler should be  attached
to. For example, SetInt 5 should be used for vertical blank interrupt code.

More  than  one  interrupt handler may be attached to a particular  type  of
erupt.

End Setint

End  SetInt  must appear after a SetInt to signify the end of a  section  of
interrupt  handler  code.  Please refer to SetInt for  more  information  of
interrupt handlers.

Clrlnt Type

ClrInt  may  be used to remove any interrupt handlers currently attached  to
the specified interrupt Type.  The SetInt command is used to attach interupt
handlers to particular interupts.

SetErr

The SetErr command allows you to set up custom error handlers.  Program code
which  appears  after  the SetErr command will be executed  when  any  Blitz
runtime  errors are caused.  Custom error code should be  ended  by  an  End
SetErr.

End SetErr

End  SetErr  must  appear  following custom error handlers  installed  using
SetErr.   Please  refer  to  SetErr tor more  information  on  custom  error
handlers.

ClrErr

ClrErr may be used to remove a custom error handler set up using SetErr.

ErrFail

ErrFail may be used within custom error handlers to cause a 'normal'  error.
The  error  which  caused the custom error handler to be  executed  will  be
reported and transfer will be passed to direct mode.

Page 100

R-2: VARIABLE HANDLING COMMANDS

To  keep  track  of numbers and text program variables are required.   These
variables are assigned a name and given a type which dictates  the  sort  of
information  they  are able to contain.  Blitz supports 5  standard  numeric
types and the string type which is used to store text type information.

Variable "arrays" are used to store a large collection of values all of  one
type,   these  arrays are similar to normal variables except  they  must  be
dimensioned (the number of elements defined) before they are used.

Blitz  offers  many  extensions to these BASIC features.   NewTypes  may  be
defined which are a collection of several standard types.  a single  NewType
variable  can  contain  an  assortment ol' numeric  and  string  information
similar to structures in C.

List  arrays  offer the programmer more control over standard arrays,   they
are  also  much  t:aster to manipulate.  Blitz contains  many  commands  for
operating on linked lists of data.

Let Var=Expression

Let  is an optional command used t<> assign a value to a variable.  Let must
always be followed by a variable name and an expression. Normally, an equals
sign ('=')  is placed between the variable name and the expression.  If  the
equals sign is omitted,  then an opertor (eg:  '+', '*') must appear between
the variable name and the expression.  In this case,  the specified variable
will be altered by the specified operator and expression.

Exchange Var,Var

Exchange  will  'swap'  the values contained in the 2  specified  variables.
Exchange may only be used with 2 variables of the same type.

MaxLen StringVar=Expression

MaxLen  sets  aside a block c>f memory for a string variable to  grow  into.
This  is normally only necessary in the case of special Blitz commands which
require this space to be present before execution.  Currently,  only 2 Blitz
commands require the use of MaxLen - FileRequest$ and Fields.

DEFTYPE . Typename [Var[, Var...]]

DEFTYPE  may be used to declare a list of variables as being of a particular
type. In this case, Var parameters must be supplied.

DEFTYPE  may  also  be  used to select a default variable  type  for  future
'unknown'  variables.   Unknown variables  are  variables  created  with  no
Typename specifier. In this case, no Var parameters are supplied.

Page 101

NEWTYPE.Typename

NEWTYPE  is used to create a custom variable type.  NEWTYPE must be followed
by  a  list  of  entry  names  separated by colons (':')   and/or  newlines.
NEWTYPEs are terminated using End NEWTYPE.

SizeOf.Typename[,Entrypath]

SizeOf allows you to determine the amount of memory,  in bytes, a particular
variable  type  takes  up.   SizeOf may also  be  followed  by  an  optional
Entrypath,   in  which case the offset from the start of  the  type  to  the
specified entry is returned.

Dim Arrayname [List] (Dimensionl[,Dimension2...])

Dim  is  used to initialize a BASIC array.  Blitz supports 2 array  types  -
simple  arrays,  and list arrays.  The optional List parameter,  if present,
denotes a list array.  Simple arrays are identical to standard BASIC arrays,
and may be of any number dimensions. List arrays may be of only I dimension.


ResetList Arraynam()

ResetList  is  used  in conjunction with a list array to  prepare  the  list
array  for  NextItem  processing.  After executing a  ResetList,   the  next
Nextitem  executed  will set the list array's 'current element'  pointer  to
the list array's very first

ClearList Arraynam()

ClearList is used in conjunction with list arrays to completely 'empty'  out
the  specified list array.  List arrays are automatically emptied when  they
are Dimmed.

AddFirst (Arrayname())

The  AddFirst  function  allows you to insert an  array  list  item  at  the
beginning  of an array list.  AddFirst returns a true/false value reflecting
whether  or  not there was enough room in the array list to add an  element.
If an array element was available,  AddFirst returns a true value (-1),  and
sets the list array's 'current item' pointer to the item added.  If no array
element was available, AddFirst returns false (0).

AddLast (Arrayname())

The  AddLast function allows you to insert an array list item at the end  of
an array list.  AddLast returns a true/false value reflecting whether or not
there  was  enough room in the array list to add an element.   If  an  array
element was available,  AddLast returns a true value (- I ),  and  sets  the
list  array's 'current item' pointer to the item added.  If no array element
was available, AddLast returns false (0).

Page 102

Additem (Arrayname())

The  AddItem function allows you to insert an array list item after the list
array's  'current'  item.   AddItem returns a  true/false  value  reflecting
whether  or  not there was enough room in the array list to add an  element.
If  an array element was available,  Additem returns a true value (-l),  and
sets the list array's 'current item' pointer to the item added.  If no array
element was available, Additem returns false (0).

KillItem ArrayName()

KillItem  is used to delete the specified list array's current item.   After
executing KillItem,  the list array's 'current item' pointer will be set  to
the item before the item deleted.

Previtem (Arrayname())

Previtem will set the specified list array's 'current item' pointer  to  the
item  before the list array's old current item.  This allows for 'backwards'
processing of a list array.  Previtem returns a true/false value  reflecting
whether or not there actually was a previous item.  If a previous  item  was
available,   PrevItem  will return true (- l ).  Otherwise,   PrevItem  will
return false (0).

Nextitem (Arrayname())

Nextitem will set the specified list array's 'current item' pointer  to  the
item  after  the list array's old current item.  This allows for  'forwards'
processing of a list array.  Nextitem returns a true/false value  reflecting
whether or not there actually was a next item available or not.  If an  item
was available,  Nextitem will return true (- l ).  Otherwise,  Nextitem will
return false (0).

Firstitem (Arrayname())

Executing  Firstitem  will  set the specified list  array's  'current  item'
pointer to the very first item in the list array.  If there are no items  in
the list array,  Firstitem will return false (0)  otherwise,  Firstitem will
return true (-l).

Lastitem (Arrayname())

Executing  Lastitem  will  set the specified  list  array's  'current  item'
pointer to the very last item in the list array.  If there are no  items  in
the  list  array,  Lastitem will return false (0),  otherwise Lastitem  will
return true (- l ).

Pushitem Arrayname()

Executing Pushitem causes the specified list array's 'current item'  pointer
to be pushed onto an internal stack.  This pointer may be later recalled  by
executing  Popitem.  The internal item pointer stack is  set  for  up  to  8
'pushes'.

Popitem Arrayname()

Popitem 'pops' or 'recalls' a previously pushed current item pointer for the
specified  list array.  Arrayname()  must match the arrayname  of  the  most
recently executed Pushitem.

Page 103

ItemStackSize Max Items

ItemStackSize  determines how many 'list' items may  be  pushed  (using  the
Pushltem  command),  before items must be 'Pop'ped off again.  For  example,
executing ItemStackSize 10()0 will allow you to push up to 1000  list  items
before you run out of item stack space.

SortList Arrayname()

The  SortList command is used to rearrange the order of elements in a  Blitz
linked  list.  The order in which the items are sorted depends on the  first
field  of the linked list type which must be a single integer word.  Sorting
criteria will be extended in future releases.

Sort Arrayname()

Sort will cause the specified array to be sorted.

The  direction  of  the sort may be specified using  either  the  SortUp  or
SortDown commands. The default direction used for sorting is ascending - ie:
array elements are sorted into a 'low to high' order.

SortUp

SortUp  may be used to force the Sort command to sort arrays into  ascending
order.  This means that,  after being sorted,  an array's contents  will  be
ordered in a 'low to high' manner.

SortDown

SortDown  may  be  used  to  force the Sort  command  to  sort  arrays  into
descending order.  This means that,  after being sorted, an array's contents
will be ordered in a 'high to low' manner.

Page 104

R-3: INPUTOUTPUT COMMANDS

Input  Output is essential for programs to function.  Input includes reading
data  from  both disk files and data statements and getting input  from  the
user.  Output options include writing data to files,  displaying information
on the screen and so on.

Input  and  Output  are  most commonly acheived  with  the  Edit  and  Print
commands,   Edit  replacing  the  standard  BASIC  Input  nomenclature.   An
assortment  of commands are available to redirect input and  output  to  and
from Files,  Windows etc. Refer to the File and Window handling sections for
more information.

Those  developing  games in Blitz should refer to the  BlitzIO  section  for
Input Output commands more suited to their particular requirements.

Print Expression[,Expresion...]

Print  allows you to output either strings or numeric values to the  current
output channel.  Commands such as WindowOutput or BitMapOutput may  be  used
to alter the current output channel.

NPrint Expression[, Expresion...]

NPrint  allows you to output either strings or numeric values to the current
output channel.  Commands such as WindowOutput or BitMapOutput may  be  used
to alter the current output channel.

After  all  Expressions  have been output,  NPrint  automatically  prints  a
newline character.

Format FormatString

Format  allows you to control the output of any numeric values by the  Print
or  NPrint  commands.   FormatString is  an  80  character  or  less  string
expression  used  for formatting information by the Print command.   Special
characters  in  FormatString   are   used   to  perform  special  formatting
functions. These special characters are:

Char    Format effect

#        If no digit to print, insert spaces into output
0        If no digit to print, insert zeros ('0') into output
        Insert decimal point into output
+        Insert sign of value
        Insert sign of value, only if negative
,        Insert commas every 3 digits to left of number

Any other characters in FormatString will appear at appropriate positions in
the output. Format also affects the operation of the Str$ function.

Page 105

FloatMode Mode

FloatMode allows you to control how floating point numbers are output by the
Print or NPrint commands.

Floating  point numbers may he displayed in one of two ways - in exponential
fon1lat, or in standard format. Exponential format displays a floating point
number as a value multiplied by ten raised to a power.  For example,   10240
expressed exponentially is displayed as '1.024E+4',  ie:  1.024 times 10  to
the power of 4. Standard format simply prints values 'as is'.

A  Mode  parameter  of  I  will cause floating point  values  to  ALWAYS  be
displayed h1 exponential format. A Mode parameter of - I will cause floating
point values to ALWAYS be displayed in standard format.  A Mode parameter of
0  will cause Blitz to take a 'best guess' at the most appropriate format to
use. This is the default mode for floating point output.

Note  that  if Format has been used to alter numeric output,  standard  mode
will always be used to print floating point numbers.

Data [.Type]ltem[ltem...]

The  Data  statement  allows  you  to include  pre-defined  values  in  your
programs.   These 'data items' may be transferred into variables  using  the
Read  statement.  When data is read into variables,  the Type  of  the  data
being read MUST match the type of the variable it is being read into

Read Var[,Var...]

Read  is used to transfer items in Data statements into variables.  Data  is
transferred  sequentially into variables through what is known  as  a  'date
pointer'.   Each  time  a  piece of data  is  read,   the  data  pointer  is
incremented to point at the next piece of data.  The data pointer may be set
to point to a particular piece of data using the Restore command.

Restore [Program Label]

Restore  allows you to set Blitz's internal 'data pointer' to  a  particular
piece of data.  after executing a Restore,  The first item of data following
the  specified Program Label will become the data to be read when  the  next
Read  command is executed.  Restore with no parameters will reset  the  data
pointer to the very first piece of data in the program.

Edit$ ([DefaultString$],Characters)

Edit$  is  Blitz's standard text input command.  When used with  Window  and
BitMap  Input Edit$ causes the optional DefaultString$ and a  cursor  to  be
printed  to  the display.  It then waits for the user to hit RETURN.   Edit$
returns the text entered by the program user as a string of character.

During  FileInput Edit$ reads the next n characters from the  open  file  or
until the next endofline character (chr$(10)).  To read data from files that
is  not  standard  ascii  (ignore EOL terminators)  Inkey$  should  be  used
instead  of  Edit$.   Characters specifies a  maximum  number  of  allowable
characters  for  input.  This is extremely useful in preventing  Edit$  from
destroying display contents.

Page 106



Edit ([DefaultValue],Characters)

Edit is Blitz's standard numeric input command. The same characteristics
apply as those for Edit$ however Edit of course only accepts numeric input.

lnkey$ [(Characters)]

Inkey$ may be used to collect one or more characters from the current  input
channel.  The current input channel may be selected using commands  such  as
WindowInput,  Filelnput or BitMapInput.  Inkey$ MAY NOT  he  used  from  the
Defaultinput  input  channel as the CLI does not  pass  input  back  to  the
program  until  the user hits return.  Characters refers to  the  number  of
characters to collect. The default is one character.

Defaultinput

Detaultinput causes all future Edit$ and Inkey$ functions to  receive  their
input  from  the  CLI window the Blitz program was run from.   This  is  the
default input channel used when a Blitz program is first run.

DefaultOutput

DefaultOutput cause all future Print statements to send their output to  the
CLI  window  the  Blitz program was run from.  This is  the  default  output
channel used when a Blitz program is first run.

FileRequest$ (Title$, Pathname$, Filename$)

The FileRequest$ function will open up a standard Amiga-style file requester
on  the currently used screen.  Program flow will halt until the user either
selects  a file,  or hits the requester's 'Cancel' button.  If  a  file  was
selected,   FileRequest$ will return the full file name  as  a  string.   If
'Cancel' was selected, FileRequest$ will return a null (empty) string.

Title$  may  be  any string expression to be used as a title  for  the  file
requester.  Pathname$ MUST be a string variable with a MaxLen  of  at  least
160. Filename$ MUST be a string variable with a MaxLen of at least 64.

Popinput

After input has been re-directed (eg using WindowInput/Filelnput),  Popinput
may be used to return the channel to it's previous condition.

PopOutput

After  output  has  been  re-directed  (eg  using  WindowOutput/FileOutput),
PopOutput may be used to return the channel to it's previous condition.

Joyx (Port)

Joyx  will  return  the  left/right status of a joystick  plugged  into  the
specified port.  Port must be either 0 or 1,  0 being the port the mouse  is
normally  plugged  into.  If the joystick is held to the  left,   Joyx  will
return -1.  If the joystick is held to the right, Joyx will return 1. If the
joystick is held neither left or right, Joyx will return 0.

Page 107

Joyy (Port)

Joyy will return the up/down status of a joystick plugged into the specified
port.   Port must be either O or 1,  0 being the port the mouse is  normally
plugged into.  If the joystick is held upwards,  Joyy will return -1. If the
joystick  is held downwrads,  Joyy will return 1.  If the joystick  is  held
neither upwards or downwards, Joyy will return 0.

Joyr (Port)

Joyr may be used to determine the rotational direction of a joystick plugged
into the specified port.  Port must be either O or 1,  port 0 being the port
the  mouse is normally plugged into.  Joyr returns a value from O through  8
based on the following table:

    Direction        Value
    Up            O
    Up-Right        1
    Right            2
    Down-Right        3
    Down            4
    Down-Left        5
    Left            6
    Up-Left            7
    No Direction    8

Joyb (Port)

Joyb  allows  you to read the button status of the device plugged  into  the
specified port.  Port must be either O or 1,  0 being the port the mouse  is
normally plugged into.  If the left button is held down, Joyb will return I.
If  the right button is held down,  Joyb will return 2.  If both buttons are
held  down,   Joyb will return 3.  If no buttons are held down,   Joyb  will
return 0.

GameB (Port#)

GameB  returns the button states of CD32 style game controllers.  The values
of  all buttons pressed are added together to make up the value returned  by
GameB.  To check a certain button is down a logical AND should be performed,
buttonvalue  AND returnvalue will evaluate to O if the button  is  not  held
down. The button values are:

.Button            Value

Play/Pause        1
Reverse            2
Forward            4
Green            8
Yellow            16
Red            32
Blue            64


Page 108



R-4: FILE HANDLING & IFF INFO COMMANDS

Blitz supports 2 modes of file access - sequential,  and random access.  The
following section covers the Blitz commands that open,  close and operate on
these two types of files.

Blitz  also  contains  special commands for finding information  about  ILBM
files  which are standard on the Amiga for containing graphics in  the  form
of bitmaps and brushes.

For  specialised commands that read and write graphics and sound files  more
information  and  command  descriptions are  available  in  the  appropriate
sections.

OpenFile (File#,Filename$)

OpenFile attempts to open the file specified by Filename$.  If the file  was
successfully opened,  OpenFile will return true (-l),  otherwise,   OpenFile
will return false (0).

Files  opened using OpenFile may be both written to and read from.   If  the
file  specified  by Filename$,  did not already exist before  the  file  was
opened, it will be created by OpenFile.

Files  opened with OpenFile are intended for use by the random  access  file
commands,   although it is quite legal to use these files  in  a  sequential
manner.

ReadFile (File#,Filename$)

ReadFile  opens  an  already  existing   file  specified  by  Filename$  for
sequential reading.  If the specified file was successfully opened, ReadFile
will return true (-l), otherwise ReadFile will return false (0).

Once  a  file  is  open  using ReadFile,  FileInput  may  be  used  to  read
information from it.

WriteFile (File#,Filename$)

WriteFile creates a new file,  specified by Filename$,  for the  purpose  of
sequential file writing. If the file was successfully opened, WriteFile will
return true (- l ), otherwise, WriteFile will return false (0).

A  file  opened  using WriteFile may be written to by using  the  FileOutput
command.

CloseFile File#

CloseFile  is  used  to  close a file opened using  one  of  the  file  open
functions (FileOpen,  ReadFile, WriteFile). This should be done to all files
when they are no longer required.

Fields File#, Var[, Var...]

Fields is used to set up fields of a random access file record.  Once Fields
is  executed,  Get and Put may be used to read and write information to  and
from  the file.  The Var parameters specify a list of variables you wish  to
be either read from,

Page 109

or written to the file.

When  a  Put  is  executed,   the values held in  these  variables  will  be
transferred to the file.  When a Get is executed,  these variables will take
on values read from the file.

Any  string  variables in the variable list MUST have  been  initialized  to
contain  a  maximum  number of characters.  This is done  using  the  MaxLen
command.   These  string variables must NEVER grow to be longer  than  their
defined maximum length.

Put File#,Record

Put is used to transfer the values contained in a Fields variable list to  a
particular  record in a random access file.  When using Put to increase  the
size  of  a  random access file,  you may only add to the immediate  end  of
file.  For example,  if you have a random access file with 5 records in  it,
it  is illegal to put record number 7 to the file until record number 6  has
been created.

Get File#,Record

Get  is  used to transfer information from a particular record of  a  random
access file into a variable list set up by the Fields command.  Only records
which also exist may be'got'.

FileOutput File#

The  FileOutput command causes the output of all subsequent Print and NPrint
commands to be sent to the specified sequential file. When the file is later
closed, Print statements should be returned to an appropriate output channel
(eg: DefaultOutput or WindowOutput).

Filelnput File#

The FileInput command causes all subsequent Edit,  Edit$ and Inkey$ commands
to  receive  their input from the specified file.  When the  file  is  later
closed,   input  should  be  redirected   to  an  appropriate  channel  (eg:
DefaultInput or WindowInput).

FileSeek File#,Position

FileSeek  allows  you to move to a particular point in the  specified  file.
The  first piece of data in a file is at position 0,  the second at position
I and so on.  Position must not be set to a value greater than the length of
the file.

Used in conjunction with OpenFile and Lof,  FileSeek may be used to 'append'
to a file.

Lof (File#)

Lof will return the length, in bytes, of the specified file.

Eof (File#)

The Eof function allows you to determine if you are currently positioned  at
the end of the specified file.  If so,  Eof will return true (-1), otherwise
Eof will return false (0).

Page 110

If  you  are  at  the end of a file,  any further writing to the  file  will
increase it's length,  while any further reading from the file will cause an
error.

Loc (File#)

Loc  may  be used to determine your current position in the specified  file.
When a file is first opened, you will be at position O in the file.

DosBuffLen Bytes

All  Blitz  file  handling  is done through the  use  of  special  buffering
routines.   This is done to increase the speed of file handling,  especially
in the case of sequential files.

Initially,  each file opened is allocated a 2048 byte buffer.  However,   if
memory  is  tight  this  buffer  size may be lowered  using  the  DosBuffLen
command.

KillFile Filename$

The  KillFile command will simply attempt to delete the specified file.   No
error will be returned if the file could not be deleted.

CatchDosErrs

Whenever you are executing AmigaDos I/O (for example,  reading or writing  a
file),   there  is  always  the possibility of something  going  wrong  (for
example,  disk not inserted...  read/write error etc.).  Normally, when such
problems  occur,  AmigaDos displays a suitable requester  on  the  WorkBench
window.  However, by executing CatchDosErrs you can force such requesters to
open on a Blitz window.

The  window you wish dos error requesters to open on should be the currently
used window at the time CatchDosErrs is executed.

ReadMem File#,Address,Length

ReadMem allows you to read a number of bytes,  determined by Length, into an
absoulte  memory  location,   determined by  Address,   from  an  open  file
specified by File#.

Be  careful  using ReadMem,  as writing to absolute memory may have  serious
consequences if you don't known what you're doing!

WriteMem File#,Address,Length

WriteMem allows you to write a number of bytes,  determined by Length,  from
an  absolute  memory  location,  determined by Address,   to  an  open  file
specified by File#.

Exists (FileName$)

Exists actually returns the length of the file,  unlike Lof()  Exists()   is
for files that have not already been opened.  If O the file either does  not
exist  or  is  empty  or is perhaps not a file at all!   Hmmm,   anyway  the
following poke turns off the "Please Insert Volume Blah:" requester  so  you
can use Exists to wait for disk changes:

Poke.l Peek.l(Peek.1(4)+276)+184,-1

Page 111

ILBMlnfo Filename$

ILBMInfo  is used to examine an ILBM file.  Once ILBMInfo has been executed.
ILBMWidth,   ILBMHeight and ILBMDepth may be used to examine  properties  of
the image contained in the file.

ILBMWidth

ILBMWidth will return the width,  in pixels,  of an ILBM image examined with
ILBMInfo.

ILBMHeight

ILBMHeight  will return the height,  in pixels,  of an ILBM  image  examined
with ILBMInfo.

ILBMDepth

ILBMDepth  wil1 return the depth,  in bitplanes,  of an ILBM image  examined
with ILBMInfo.

ILBMViewMode

ILBMViewMode  returns  the  viewmode of  the  file  that  was  processed  by
ILBMInfo. This is useful for opening a screen in the right mode before using
LoadScreen  etc.   The different values of ViewMode are as  follows  (add/or
them for different combinations):

    Mode        Value
    HiRes        32768
    Ham        2048
    HalfBrite    128
    Interlace    4
    LoRes        0

Page 112


R-5: NUMERIC & STRING FUNCTIONS

This section covers all Blitz functions which accept and return numeric  and
string values.  Note that all the transcendental functions (eg.  Sin,   Cos)
operate in radians.

Functions  that  return information about system time and  date.   workbench
parameters and so forth are also listed in this section.

True

True is a system constant with a value of -1.

False

False is a system constant with a value of 0.

NTSC

This function returns O if the display is currently in PAL mode,  or  -I  if
currently  in  NTSC  mode.   This  may  be  used  to  write  software  which
dynamically adjusts itself to different versions of the Amiga computer.

DispHeight

DispHeight will return 256 if executed on a PAL Amiga, or 200 if executed on
an NTSC Amiga.  This allows programs to open full sized screens, windows etc
on any Amiga.

VPos

VPos  returns the video's beam vertical position.  Useful in both  highspeed
animation where screen update may need to be synced to a certain video  beam
position  (not just the top of frame as with VWait)  and for a  fast  random
nember generator in non frame-synced applications.

Peek [.Type](Address)

The  Peek  function  returns the contents of the  absolute  memory  location
specified  by  Address.   The  optional Type  parameter  allows  peeking  of
different sizes.  For example, to peek a byte, you would use Peek.b; to peek
a word, you would use Peek.w; and to peek a long, you would use Peek.l

It is also possible to peek a string using Peek$.  This will return a string
of  characters read from consecutive memory locations until a byte of  O  is
found.

Abs (Expression)

This function returns the positive equivalent of Expression.

Frac (Expression)

Frac() returns the fractional part of Expression.

Page 113

Int (Expression)

This returns the Integer part (before the decimal point) of Expression.

OAbs (Ouick)

QAbs  works just like Abs except that the value it accepts is a Quick.  This
enhances  the  speed at which the function executes quite dramatically.   Of
course you are limited by the restrictions of the quick type of value.

QFrac (Ouick)

QFrac()  returns the fractional part of a quick value.  It works like Frac()
but  accepts a quick value as it's argument.  It is faster than Frac()   but
has the normal quick value limits.

OLimit (Ouick,Low,High)

QLimit  is  used to limit the range of a quick number.  If Quick is  greater
than or equal to Low,  and less than or equal to High, the value of Quick is
returned.  If Quick is less than Low,  then Low is returned.   If  Quick  is
greater than High, then High is returned.

QWrap (Ouick,Low,High)

QWrap will wrap the result of the Quick expression if Quick is greater  than
or equal to high,  or less than low.  If Quick is less than Low, then Quick-
Low+High is returned. If Quick is greater than or equal to High, then Quick-
High+Low is returned.

Rnd [(Range)]

This  function  returns a random number.  If Range is not specified  then  a
random decimal is returned between O and 1.  If Range is specified,  then  a
decimal value between O and Range is returned.

Sgn (Expression)

Sgn returns the sign of Expression.  If Expression is less than 0,  then - I
is returned.  If Expression is equal to 0, then O is returned. If Expression
is greater than 0, then I is returned.

Cos (Float)  Cos()  returns the Cosine of the value Float.  Sin (Float) This
returns the Sine of the value Float.

Tan (Float)

This returns the Tangent of the value Float.

Page 114

ACos (Float)

This returns the ArcCosine of the value Float.

ASin (Float)

This returns the ArcSine of the value Float.

ATan (Float)

This returns the ArcTangent of the value Float.

HCos (Float)

This returns the hyperbolic Cosine of the value Float.

HSin (Float)

This returns the hyperbolic Sine of the value Float.

HTan (Float)

This returns the hyperbolic Tangent of the value Float.

Exp (Float)

This returns e raised to the power of Float.

Sqr (Float)

This returns the square root of Float.

LoglO (Float)

This returns the base 101ogarithm of Float.

Log (Float)

This returns the natural (base e) logarithm of Float.

QAngle (Src X,Src Y,Dest X,Dest Y)

QAngle returns the angle between the two 2D coordinates passed.  the angle.q
returned is a value from 0..1,  I representing 360 degrees in standard polar
geometry.

Left$ (String$,Length)

This function returns the Length leftmost characters of string String$.

Right$ (String$,Length)

Right$() returns the rightmost Length characters from string String$.

Page 115



Mid$ (String$,Startchar[ Length])

This  function  returns  Length characters of  string  String$  starting  at
character Startchar.  If the optional Length parameter is omitted,  then all
characters from Startchar up to the end of String$ will be returned.

Hex$ (Expression)

Hex$()   returns  an  8  character  string  equivalent  to  the  hexadecimal
representation of Expression.

Bin$ (Expression)

Hex$()   returns   a   32   character   string   equivalent  to  the  binary
representation of Expression.

Chr$ (Expression)

Chr$  returns  a  one  character string equivalent to  the  ASCII  character
Expression.Ascii  is  a standard way of coding the characters  used  by  the
computer display.

Asc (String$)

Asc() returns the ASCII value of the first characters in the string String$.
String$ (String$,Repeats)

This  function  will  return   a   string   containing   Repeats  sequential
occurrences of the string String$.

Instr (String$,Findstring$[,Startpos])

Instr  attempts to locate FindString$ within String$.  If a match is  found,
the character position of the first matching character will be returned.  If
no match is found, O will be returned.

The  optional Startpos parameter allows you to specify a starting  character
position for the search.

CaseSense  may be used to determine whether the search is case sensitive  or
not.

Replace$ (String$,Findstring$,Replacestring$)

Replace$()  will search the string String$ for any occurrences of the string
Findstring$ and replace it with the string Replacestring$.

CaseSense  may be used to determine whether the search is case sensitive  or
not.

Mki$ (Integer)

This  will  create a two byte character string,  given the two byte  numeric
value  Numeric.   Mki$  is  often  used before  writing  integer  values  to
sequential files to save on disk space.  When the file is later read in, Cvi
may be used to convert the string back to an integer.

Page 116

Mk|$ (Long)

This  will create a four byte character string,  given the four byte numeric
value Long.  Mkl$ is often used when writing long values to sequential files
to save on disk space.  When the file is later read in,  Cvl may be used  to
convert the string back to a long.

Mkq$ (Quick)

This  will create a four byte character string,  given the four byte numeric
value  Quick.   Mkq$ is often used when writing quick values  to  sequential
files  to save on disk space.  When the file is later read in,  Cvq  may  be
used to convert the string back to a quick.

Cvi (String$)

Cvi  returns  an  integer  value equivalent to  the  left  2  characters  of
String$. This is the logical opposite of Mki$.

Cvl (String$)

Cvl  returns  a long value equivalent to the left 4 characters  of  String$.
This is the logical opposite of Mkl$.

Cvq (String$)

Cvq  returns a quick value equivalent to the left 4 characters  of  String$.
This is the logical opposite of Mkq$.

Len (String$)

Len returns the length of the string String$.

UnLeft$ (String$,Length)

UnLeft$() removes the rightmost Length characters from the string String$.

UnRight$ (String$,Length)

UnRight$() removes the leftmost Length characters from the string String$.

Strip Lead$ (String$, Expression)

StripLead$ removes all leading occurrences of the ASCII character  specified
by Expression from the string String$.

StripTrai 1$ (String$, Expression)

StripTrail$  removes  all  trailing   occurrences  of  the  ASCII  character
specified by Expression from the string String$.

LSet$ (String$, Characters)

This  function returns a string of Characters characters long.   The  string
String$

Page 117

will be placed at the beginning of this string.  If String$ is shorter  than
Characters the right hand side is padded with spaces.  If it is longer,   it
will be truncated.

RSet$ (String$, Characters)

This  function returns a string of Characters characters long.   The  string
String$  will be placed at end of this string.  If String$ is  shorter  than
Characters the lett hand side is padded with spaces.  If it is  longer,   it
will be truncated.

Centre$ (String$,Characters)

This  function returns a string of Characters characters long.   The  string
String$  will  be centered in the resulting string.  If String$  is  shorter
than Characters the left and right sides will be padded with spaces.  If  it
is longer, it will be truncated on either side.

LCase$ (String$)

This function returns the string String$ converted into lowercase.

UCase$ (Siring$)

This function returns the string String$ converted to uppercase.

CaseSense Onl Off

CaseSense  allows you to control the searching mode used by  the  Instr  and
Replace$ functions.

CaseSense On indicates that an exact match must be found.

CaseSense  Off indicates that alphabetic characters may be matched  even  if
they are not in the same case.

CaseSense On is the default search mode.

Val (String$)

This  functions converts the string String$ into a numeric value and returns
this value.  When converting the string, the conversion will stop the moment
either a non numeric value or a second decimal point is reached.

Str$ (Expression)

This returns a string equivalent of the numeric value Expression.  This  now
allows you to perform string operations on this string.

If  the Format command has been used to alter numeric output,  this will  be
applied to the resultant string.

UStr$ (Expression)

This returns a string equivalent of the numeric value Expression.  This  now
allows you to perform string operations on this string.

Unlike Str$, UStr$ is not affected by any active Format commands.

Page 118

SystemDate

SystemDate  returns  the  system date as the number  of  days  passed  since
1/1/1978.

Date$ (days)

Date$  converts  the  format  returned  by  SystemDate  (days  passed  since
1/1/1978)  into a string format of dd/mm/yyyy or mm/dd/yyyy depending on the
dateformat (defaults to 0)

NumDays (date$)

Numdays converts a Date$ in the above format to the day count format,  where
numdays is the number of days since 1/1/1978.

DateFormat format#; O or 1

DateFormat  configures  the  way  both date$  and  numdays  treat  a  string
representation of the date: O=dd/mm/yyyy and l=mm/dd/yyyy

Days

Days Months and Years each return the particular value relevant to the  last
call  to  SystemDate.  They are most useful for when the  program  needs  to
format  the  output of the date other than that produced by date$.   WeekDay
returns which day of the week it is with Sunday=0 through to Saturday=6.

Months

See description of Days.

Years

See description of Days.

WeekDay

See description of Days.

Hours

Hours, Mins and Secs return the time of day when SystemDate was last called.
Mins

Hours, Mins and Secs return the time of day when SystemDate was last called.
Secs

Hours, Mins and Secs return the time of day when SystemDate was last called.
Page 119

WBWidth

The  functions WBWidth,  WBHeight,  WBDepth & WBViewMode return  the  width,
height,   depth & viewmode of the current WorkBench screen as configured  by
preferences.

WBHeight

See Description of WBWidth.

WBDepth

See Description of WBWidth.

WBViewMode

See Description of WBWidth.

Processor

The  function  Processor returns the type of processor in  the  computer  on
which the program is currently running.

0=68000
1=680l0
2=68020
3=68030
4=68040

ExecVersion

The  function ExecVersion returns the relevant information about the  system
the program is running on.

33=1.2
34=1.3
36=2.0
39=3.0

Page 120


R-6: COMPILER DIRECTIVES & OBJECT HANDLING

The  following  section  refers to the Blitz Compiler Directives,   commands
which  affect  how  a program is compiled.  Conditional compiling,   macros,
include files and more are covered in this chapter.

Information  regarding  control of Blitz Objects  is  also  listed  in  this
section.  Objects are Blitz's way of controlling speicalised data  concerned
with windows, shapes etc.

USEPATH Pathtext

USEPATH allows you to specify a 'shortcut' path when dealing with
NEWTYPE variables. Consider the following lines of code:

aliens()\x= 1 60
al iens()\y= 100
aliens()\xs= 10
aliens()\ys=-10
USEPATH can be used to save you some typing, like so:
USEPATH aliens()

\x=160
\y=100
\xs=10
\ys=-10
Whenever  Blitz encounters a variable starting with the backslash  character
('\'), it simply inserts the current USEPATH text before the backslash.

BLITZ

The  BLITZ directive is used to enter Blitz mode.  For a full discussion  on
Amiga/Blitz  mode,  please refer to the programming  chapter  of  the  Blitz
Programmers Guide.

AMIGA

The  AMIGA directive is used to enter Amiga mode.  For a full discussion  on
Amiga/Blitz  mode,  please refer to the programming  chapter  of  the  Blitz
Programmers Guide.

QAMIGA

The  QAMIGA  directive  is  used to enter Quick  Amiga  mode.   For  a  full
discussion on Amiga/Blitz mode,  please refer to the programming chapter  of
the Blitz Programmers Guide.

INCLUDE Filename

INCLUDE  is  a  compile  time  directive which causes  the  specified  file,
Filename,  to be compiled as part of the programs object code. The file must
be  in tokenised form (de:  saved from the Blitz editor)  - ascii files  may
not  be  INCLUDE'd.   INCDIR may be used to specify  a  path  for  Filename.
Filename may be optionally quote enclosed to avoid tokenisation problems.

Page 121

XINCLUDE Filename

XINCLUDE  stands  for  exclusive  include.  XINCLUDE  works  identically  to
INCLUDE  with  the  exception that XlNCLUDE'd files are only  ever  included
once.   For example,  if a program has 2 XINCLUDE statements with  the  same
filename, only the first XINCLUDE will have any effect.

INCDIR  may  be  used  to  specify a path for  Filename.   Filename  may  be
optionally quote enclosed to avoid tokenisation problems.

INCBIN Filename

INCBIN  allows you to include a binary file in your object  code.   This  is
mainly  of use to assembler language programmers,  as having big  chunks  of
binary data in the middle of a BASIC program is not really a good idea.

INCDIR may be used to specify an AmigaDos path for Filename.

Filename may be optionally quote enclosed to avoid tokenisation problems.

INCDIR Pathname

The INCDIR command allows you to specify an AmigaDos path to be prefixed  to
any. filenames specified by any of INCLUDE, XINCLUDE or INCBIN commands.

Pathname may be optionally quote enclosed to avoid tokenisation problems.

CNIF Constant Comparison Constant

CNIF allows you to conditionally compile a section of program code based  on
a  comparison of 2 constants.  Comparison should be one of '<',  '>',   '=',
'<>',  '<=' or'>='. If the comparison proves to be true, then compiling will
continue as normal.  If the comparison proves to be false,  then  no  object
code will be generated until a matching CEND is encountered.

CEND

CEND  marks  the end of a block of conditionally compiled code.   CEND  must
always appear somewhere following a CNIF or CSIF directive.

CSIF "String" Comparison "String"

CSIF allows you to conditionally compile a section of program code based  on
a  comparison of 2 literal strings.  Comparison should be one of '<',   '>',
'=',   '<>',   '<='  or'>='.  Both strings must be  quote  enclosed  literal
strings.  If the comparison proves to be true,  then compiling will continue
as  normal.  If the comparison proves to be false,  then no object code will
be generated until a matching CEND is encountered.

CSIF is of most use in macros for checking macro parameters.

CELSE

CELSE  may be used between a CNIF or CSIF,  and a CEND to cause code  to  be
compiled when a constant comparison proves to be false.

Page 122

CERR Errormessage

CERR  allows  a  program to generate compile-time error messages.   CERR  is
normally  used  in  conjunction with macros  and  conditional  compiling  to
generate errors when incorrect macro parameters are encountered.

Macro Macroname

Macro is used to declare the start of a macro definition. All text following
Macro,   up  until  the  next End Macro,  will be included  in  the  macro's
contents.

End Macro

End Macro is used to finish a macro definition. Macro definitions are set up
using the Macro command.

Runerrson

These  two  new  compiler directives are for enabling  and  disabling  error
checking  in different parts of the program,  they override the settings  in
Compiler Options.

Runerrsoff

See description of Runerrson.

Use Objectname Object#

Use  will  cause  the Blitz object specified by Objectname  and  Object#  to
become the currently used object.

Free Objectname Object#

Free  is  used to free a Blitz object.  Any memory consumed by the  object's
existence will be free'd up,  and in the case of things such as windows  and
screens, the display may be altered.

Attempting to free a non-existent object will have no effect.

USED ObjectName

Used  returns the currently used object number.  This is useful for routines
which  need to operate on the currently used object,  also interrupts should
restore currently used object settings.

Addr Objectname(Object#)

Addr  is  a low-level function allowing advanced programmers the ability  to
find where a particular Blitz object resides in RAM.  An appendix at the end
of this manual lists all Blitz object formats.

Maximum Objectname

The  Maximum  function allows a program to determine the  'maximum'  setting
for a particular Blitz object. Maximum settings are entered into the

Page 123

OPTIONS  retiuester,  accessed throu5:h the 'COMPILER'  menu  of  the  Blitz
eciitor.

Page 124

R-7: ASSEMBLER DIRECTIVES

A  powerful  feature of Blitz is it's huilt in assctmbitr  This  allows  the
programmer  to  include machine code in their progams Thosc fatililiat  with
6X()()()   assembler.` ul find the ability to mix easy to cotle  BASIC  with
their own lightning fast machine code routines a powertul concoction.

Thete arc three ways of including assembler in Blitz prograns.

Inline:  using PutRrg and GetReg BASIC variables can be exchanged  with  the
68000's data and address registers.

Proceclures:   Statements   and   Functions   can  contain  100%  assembler,
parameters are passed in registers d()..d5 and in the case of Functions  the
value  in  D0 is returned to the caller.  The AsmlExit commmand is  used  in
place of StatmentReturn or FunctionReturn.

Libraries  Actual commands can he added to Blitz using assembler.   see  the
libsdev archive in the blitzlibs: volume fot more information.

Please  note  that when using assmbler inline and within procedures  address
registers A4-A6 must he preserved.  Blitz uses A5 as a glohal variable base.
A4  as  a local variable base,  and tries to keep A6 from having to  be  be-
loaded too often.

Also  note  that Absolute Short addeessing mode and Short Branches  are  not
suppotted.

DCB [.Size] Repeats,Data

DCB  stantd  for  'define  cotistant block' .DCB  allows  you  to  insert  a
repeating series of the satire value into your assemblet programs.

EVEN

EVEN allows you to word align B1itz's internal program counter.  This may be
necessary if a DC,  DCB or DS statement has caused the program counter to be
left at an odd adtitess.

GetReg 68000 Reg,Expression

GetReg allows you to tranfer the result of a BASIC expressition to  a  68000
register.  The result of the expression will first be converted into a  long
value  before being moved to the data register.  GetReg should only he  used
to transfer expressions to one of the 8 data registers (d0-d7).  GetReg will
use the stack to temporarily store any registers used in calculation of  the
expression.

PutReg 68000 Reg, Variable

PutReg may he used to transfer a vlue from any 68000 register (d0-d7/a0-a7)

Page 125

into a BASIC variable.  If the specified variable is a string,  long,  float
or  quick,  then all 4 bytes from the register will be transferred.  If  the
specified  variable is a word or a byte,  then only the relevant  low  bytes
will be transferred.

SysJsr Boutine

SysJsr  allows  you  to call any of Blitz's system routines  from  your  own
program. Routine specifies a routine number to call.

TokeJsr Token[,Form]

TokeJsr  allows  you to call any of Blitz's library based  routines.   Token
refers to either a token number,  or an actual token name.  Form refers to a
particular form of the token.  A full list of all token numbers  with  their
various forms will be available shortly trom Acid Software.

ALibJsr Token[,Form]

ALibJsr  is only used when writing Blitz libraries.  ALibJsr allows  you  to
call  a  routine from another library from within your own library.   Please
refer  to  the  Library Writing section of the programmers  guide  for  more
information on library writing.

BLibJsr Token[,Form]

BLibJsr  is only used when writing Blitz libraries.  BLibJsr allows  you  to
call  a  routine from another library from within your own library.   Please
refer  to  the  Library Writing section of the programmers  guide  for  more
information on library writing.

AsmExit

AsmExit  is used to exit from functions and statements written in assembler.
Remember  also  that  registers A4-A6 must be  preserved  in  functions  and
statements written in assembler.

Page 126

R-8: MEMORY CONTROL COMMANDS

This  section deals with low-level commands which allow you  access  to  the
Amiga's memory.  Care must be taken when accessing memory in this way or  an
invitation to the alert guru may be mistakenly made.

Poke [.Type] Address,Data

The  Poke  command  will place the specified Data into the  absolute  memory
location specified by Address.  The size of the Poke may be specified by the
optional Type parameter.  For example, to poke a byte into memory, you would
use Poke.b;  to poke a word into memory you would use Poke.w;  and to poke a
long word into memory you would use Poke.l

In  addition,  strings may be poked into memory by use of Poke$.  This  will
cause the ascii code of all characters in the string specified by Data to be
poked,  byte by byte,  into consecutive memory locations. An extra 0 is also
poked past the end of the string.

Peek [. Type](Address)

The  Peek  function  returns the contents of the  absolute  memory  location
specified  by  Address.   The  optional Type  parameter  allows  peeking  of
different sizes.  For example, to peek a byte, you would use Peek.b; to peek
a word, you would use Peek.w; and to peek a long, you would use Peek.l

It is also possible to peek a string using Peek$.  This will return a string
of  characters read trom consecutive memory locations until a byte of  0  is
found.

Peeks$ (Address,length)

Peeks$ will return a string of characters corresponding to bytes peeked from
consective  memory locations starting at Address,  and Length characters  in
length.

Call Address

Call  will  cause  program flow to be transferred  to  the  absolute  memory
location specified by Address.

PLEASE  NOTE!  Call is for advanced programmers only,  as incorrect  use  of
Call can lead to severe problems - GURUS etc!

A  68000 JSR instruction is used to transfer program flow,  so an RTS may be
used to transfer back to the Blitz program.

Please  refer to the 'Assembler' section of the manual for the rules machine
code programs must follow to operate correctly within the Blitz environment.
Page 127

Bank (Bank#)

Returns  the meniory location of the given memory Bank,  replaces the  older
and more stupidly named BankLoc command.

BankSize (Bank#)

BankSize  returns the size of the memory hlock allocated for  the  specified
Bank#.

lnitBank  Bank#,size,memtype  InitBank  allocates  a  hlock  ot  memory  and
assigns  it  to the Bank specified.  The memtype is the same  as  the  Amiga
operating system men1ory flags: l = public 2 = chip 65536 = clear memory

FreeBank Bank#

FreeBank de-allocates any memory block allocated tor the Bank specified.

LoadBank Bank#,FileName$[,MemType]

The LoadBank command has been modified,  instead of having to initialise the
bank  before loading a file,  LoadBank will now initialise the bank  to  the
size  of  the  file  if  it  is not already large enough  or  has  not  been
initialised at all.

SaveBank Bank#,filename$

SaveBank  will  save  the  memory assigned  to  the  Bank  to  the  filename
specified.

AllocMem (size,type)

Unlike  calling  Exec's AllocMem_ command directly Blitz will  automatically
free any allocated memory when the program ends.  Programmers are advised to
use  the  InitBank  command.  Flags that can be used with  the  memory  type
parameter are:  l=public ;fast if present 2=chipmem 65536=clear ;clears  all
memory allocated with O's

FreeMem location,size

Used to tree any memory allocated with the AllocMem command.

Page 128

R-9: PROGRAM STARTUP COMMANDS

This  section covers all commands dealing with how an executable  file  goes
about starting up.  This includes the ability to allow your programs to  run
from Workbench, and to pick up parameters supplied through the CLI.

WBStartup

By executing WBStartup at some point in your program,  your program will  be
given the ability to run from Workbench.  A program run from Workbench which
does NOT include the WBStartup command will promptly crash if an attempt  is
made to run it from Workbench.

- NumPars

The  NumPars  function  allows an executable  file  to  determine  how  many
parameters  were  passed to it by either Workbench or the  CLI.   Parameters
passed  from  the CLI are typed following the program name and separated  by
spaces.

For example. Iet's say you have created an executable program called myprog,
and run it trom the CLI in the following way:

myprog filer Olle2

In  this  case,  NumPars would return the value '2' - 'file I ' and  'file2'
beng the 2 parameters.

Programs  run  from  Workbench are only capable of picking  up  I  parameter
through the use of either the parameter file's 'Default Tool' entry in  it's
'.info' file, or by use of multiple selection through the 'Shift' key.

If no parameters are supplied to an executable file,  NumPars will return 0.
During program development,  the 'CLI Arguement' menu item in the 'COMPILER'
menu allows you to test out CLI parameters.

Par$ (Parameter)

Par$ return a striny equivalent to a parameter passed to an executable  file
through  either  the CLI or Workbench.  Please refer  to  NumPars  for  more
information on parameter passiny.

CloseEd

The  CloseEd  statetnent will cause the Blitz editor screen to 'close  down'
when  programs  are executed from within Blitz.  This  may  be  useful  when
writing  programs which use a large amount of chip memory,   as  the  editor
screen itself occupies about 40K of chip memory.

CloseEd  will have no effect on executable files run outside  of  the  Blitz
environment.

NoCli

NoCli  will prevent the nonnal 'Default Cli' from opening when programs  are
executed  from  within Blitz.  NoCli has no effect on executable  files  run
outside of the Blitz environment.

Page 129

FromCLI

Returns TRUE (-1)  if your program was run from the CLI, or FALSE (O) if run
from the WorkBench.

ParPath$ (parameter,type)

ParPath$  returns the path that the parameter resides in,  'type'  specifies
how you want the path returned:

0  You  want only the directory of the parameter returned.  1    You  want  the
directory along with the parameter name returned.

If you passed the parameter "FRED" to your program from WorkBench,  and FRED
resides  in  the  directory   "work:mystuff/myprograms"  then  ParPath$(0,0)
willreturn  "work:mystuff/myprograms",    but   ParPath$(0,1)   will  return
"work:mystuff/myprograms/FRED".

The  way WB handles argument passing of directories is different to that  of
files.   When a directory is passed as an argument,  ArgsLib gets  an  empty
string for the name,  and the directory string holds the path to the  passed
directory AND the directory name itself.

Page 130

R-10: SLICE COMMANDS

Slices  are  Blitz  objects which are the heart  of  Blitz  mode's  powerful
graphics  system.   Through the use of slices,   many  weird  and  wonderful
graphical effects can be achieved,  effects not normally possible  in  Amiga
mode.   This  includes  such  things  as dual  playfield  displays,   smooth
scrolling, double buffering and more.

A  slice  may  be  thought of as a 'description'  of  the  appearance  of  a
rectangular area of the Amiga's display.  This description includes  display
mode,  colour palette,  sprite and bitplane information. More than one slice
may be set up at a time,  allowing different areas of the display to take on
different properties.

Slices  must  not  overlap in any way (at least two Scan lines  is  required
between each slice). They may not be positioned side by side.

Slice  Slice#,Y,Flags  Slice#,   Y,    Width,Height,Flags,BitPlanes,Sprites,
Colours, w1, w2

The  Slice  command  is  used to create a Blitz slice  object.   Slices  are
primarily  of  use in Blitz mode,  allowing you to create highly  customized
displays.

In  both forms of the Slice command,  the Y parameter specifies the vertical
pixel  position  of  the top of the slice.  A Y value of  44  will  position
slices at about the top of the display.

In  the  first  torm of the Slice command,  Flags refers to  the  number  of
bitplanes  in any bitmaps (the bitmap's depth)  to be shown  in  the  slice.
This form of the Slice command will normally create a lo-res slice,  however
this  may  be  changed  to  a  hi-res slice by adding  eight  to  the  Flags
parameter.  For instance,  a Flags value of tour will set up  a  lo-res,   4
bitplane (16 colour)  slice,  whereas a Flags value of ten will set up a hi-
res,  2 bitplane (4 colour)  slice.  The width of a slice set up in this way
will  be  320 pixels for a lo-res slice,  or 640 pixels for a hi-res  slice.
The  height  of a slice set up using this syntax will be 200  pixels  on  an
NTSC Amiga, or 256 pixels on a PAL Amiga.

The second form of the Slice command is far more versatile,  albeit a little
more  complex.  Width and Height allow you to use specific  values  for  the
slice's dimensions. These parameters are specified in pixel amounts.

BitPlanes  refers to the depth of any bitmaps you will be  showing  in  this
slice.

Sprites  refers  to  how many sprite channels should be  available  in  this
slice.  Each slice may have up to eight sprite channels,  allow, ing sprites
to  be 'multiplexed'.  This is one way to overcome the Amiga's 'eight sprite
limit'.  It is recommended that the top-most slice be created with all eight
sprite  channels,   as  this will prevent sprite flicker  caused  by  unused
sprites.

Colours  refers to how many colour palette entries should be  available  for
this slice, and should not be greater than 32.

Widthl and Width2 specify the width,  in pixels,  of any bitmaps to be shown
in  this  slice.  If a slice is set up to be a dual-playfield slice,  Widthl
refers  to the width of the 'foreground' bitmap,  and Width2 refers  to  the
width  of the 'background' bitmap.  If a slice is NOT set up to be  a  dual-
playfield  slice,  both Width I and Width2 should be set to the same  value.
These  parameters allow you to show bitmaps which are wider than the  slice,
introducing the ability to smooth scroll through large bitmaps.

Page 131

The  Flags  parameter has been lett to last because it is the most  complex.
Flags  allows  you control over many aspects of the slices appearance,   and
just what ettect the slice has. Here are some example settings for Flags:

    Fiags    Effect                                    Max BitPlanes

    $ftf8A    Standard lo-res slice                        6
    $fft9A    Standard hi-res slice                        4
    $fitaA    Lo- res, dual -pl ayfield slice                6
    $tfibA    Hi-res, dual-playfiled slice                4
    $fffcA    HAM slice                                    6

WARNING - the next bit is definitely for the more advanced users out  there!
Knowledge of the following is NOT necessary to make good use of slices.

Flags  is  actually  a  collection of individual bit-flags.   The  bit-flags
control how the slices 'copper list' is created Here is a list of  the  bits
numbers and their ettect:

    Bit#    Effect
    15    Create copper MOVE BPLCON0
    14    Create copper MOVE BPLCONI
    13    Create copper MOVE BPLCON2
    12    Create copper MOVE DIWSTRT and MOVE DIWSTOP
    I0    Create copper MOVE DDFSTRT and MOVE DDFSTOP
    8    Create copper MOVE BPL I MOD
    7    Create copper MOVE BPL2MOD
    4    Create a 2 line 'blank' above top of slice
    3    Allow for smooth horizontal scrolling
    2    HAM slice
    I    Dual-playtield slice
    0    Hi-res slice - default is lo-res

Clever  selection of these bits allows you to create 'minimal' slices  which
may only attect specific system registers.

The  BitPlanes parameter may also be modified to specify 'odd only' or 'even
only' bitplanes.  This is of use when using dual playfield displays,  as  it
allowing  you  to  create a mid display slice which  may  show  a  different
foreground  or  background  bitmap leaving the  other  intact.   To  specify
creation  of foreground bitplanes only,  simply set bit 15 of the  BitPlanes
parameter.  To specify creation of background bitplanes only,  set bit 14 of
the BitPlanes parameter

Use Slice Slice#

Use  Slice  is used to set the specified slice object as being the currently
used slice.  This is required tor commands such as Show,  ShowF,  ShowB  and
Blitz mode RGB.

Page 132


FreeSlices

FreeSlices is used to completely free all slices currently in use.  As there
is no capability to Free individual slices,  this is the only means by which
slices may be deleted.

Show Bitmap#[,X, Y]

Show  is  used to display a bitmap in the currently used slice.  This  slice
should not be a dual-playfield type slice.  Optional X and Y parameters  may
be used to position the bitmap at a point other than it's top-left.  This is
normally  only  of use in cases where a bitmap larger than the  slice  width
and/or height has been set up.

ShowF BitMap#[,X, Y[,ShowB X]]

ShowF  is  used to display a bitmap in the foreground of the currently  used
slice.   The  slice  must  have  been created  with  the  appropriate  Flags
parameter in order to support dual-playfield display.

Optional X and Y parameters may be used to show the bitmap at a point  other
than  it's  top-left.   Omitting the X and  Y  parameters  is  identical  to
supplying X and Y values of ().

The optional ShowB x parameter is only of use in special situations where  a
dual-playfield  slice has been created to display ONLY a foreground  bitmap.
In this case,  the X offset of the background bitmap should be specified  in
the ShowB x parameter.

ShowB BitMap#[,X,Y[,ShowFX]]

ShowB  is  used to display a bitmap in the background of the currently  used
slice.   The  slice  must  have  been created  with  the  appropriate  Flags
parameter in order to support dual-playfield display.

Optional X and Y parameters may be used to show the bitmap at a point  other
than  it's  top-lett.   Omitting the X and  Y  parameters  is  identical  to
supplying X and Y values of 0.

The optional ShowF x parameter is only of use in special situations where  a
dual-playfield  slice has been created to display ONLY a background  bitmap.
In this case,  the X offset of the foreground bitmap should be specified  in
the ShowF x parameter.

ColSplit ColourRegister,Red,Green,Blue,Y

ColSplit  allows  you  to change any of the palette colour  registers  at  a
position  relative to the top of the currently used slice.  This allows  you
to  're-use'  colour registers at different positions  down  the  screen  to
display different colours.  Y specifies a vertical offset fi-om the  top  of
the currently used slice.

CustomCop Copin$, Y

CustomCop  allows  advanced  programmers   to  introduce  their  own  copper
instructions at a specified position down the display.  Copins$ refers to  a
string  of  characters  equivalent to a series of  copper  instructions.   Y
refers to a

Page 133

position down the display.

ShowBlitz

ShowBlitz redisplays the entire set up of slices.  This may be necessary  if
you have made a quick trip into Amiga mode, and wish to return to Blitz mode
with previously created slices intact.

CopLoc

CopLoc returns the memory address of the Blitz mode copper list. All Slices,
ColSplits, and CustomCops executed are merged into a single copper list, the
address of which may found using the CopLoc function.

CopLen

CopLen  returns the length,  in bytes,  of the Blitz mode copper list.   All
Slices,  ColSplits,  and CustomCops executed are merged into a single copper
list, the length of which may found using the CopLen function.

Display On| Off

Display is a blitz mode only command which allows you to 'turn on' or  'turn
off'  the  entire display.  If the display is turned off,  the display  will
appear as a solid block of colour 0.

SetBPLCON0 Default

The  SetBPLCON0 command has been added for advanced control of Slice display
modes.   The  BPLCON0  hardware register is on page A4-l  of  the  reference
manual (appendix 4). The bits of interest are as follows:

bit#l  ERSY external sync (for genlock enabling)  bit#2 LACE interlace  mode
bit#3 LPEN light pen enable

Page 134

R-11: DISPLAY LIBRARY COMMANDS

The new display library is an alternative to the slice library.  Instead  of
extending  the  slice  library  for AGA support  a  completely  new  display
library has been developed.

Besides  support for extended sprites,  super hires scrolling and 8 bitplane
displays  a  more  modular method of creating displays has been  implemented
with  the  use of CopLists.  CopLists need only be initialised once  at  the
start of the program.  Displays can then be created using any combination of
CopLists.  Most importantly the CreateDisplay command does not allocate  any
memory avoiding any memory fragmenting problems.  The new display library is
for non-AGA displays also.

To  create  displays the InitCopList command is used to allocate memory  for
what were up till now known as Slices.  A display is then created by linking
one or more of these coplists together into a single display.

With  many  of  the new AGA modes sprite DMA has been screwed  up  something
severe.   Those wanting to use 8 bitplanes and 8 sprites in  lores  will  be
disapointed to hear that their displays must be modified to some 256  pixels
across.

The  way the Amiga fetches data for each scanline is also a little different
with the AGA machines.  The effect is that displays have to be created  more
to the right than usual so the system has time to fetch sprites.

InitCopList CopList#,ypos,height,type,sprites,colors,customs

InitCopList  is  used  to  create a CopList for use with  the  CreateDisplay
command.

The ypos and height parameters define the vertical section of the screen the
display will take up.

Sprites, Colors and Customs will allocate instructions for that many sprites
(always=8!)  colors (yes,  as many as 256!)  and custom copper  instructions
(which need to be allocated to take advantage of the custom commands  listed
at the end of this section).

A  shortened  version  of the InitCopList command is available  that  simply
requires  the CopList# and the Type.  From the Type it fills in the  missing
parameters.

As  with  slices several lines must be left between coplists when displaying
more than one.

Page 135

The  following  constants make up the type patameter,   add  the  number  of
bitplanes to the total to make up the type parameter:

    Type                                        Value

    #smoothscroll                                 $10
    #dualplayfield                                $20
    #extrahalibrite                                $40
    #ham                                        $8O
    #lores                                        $000
    #hires                                        $100
    #super                                        $200
    #loressprites                                $400
    #hiressprites                                $800
    #supersprites                                $cO0
    #fmode0                                     $0000
    #fmode1                                     $1000
    #fmode2                                        $2000
    #fmode3                                        $3000
    #agapalette                                    $10000

Fot  displays  on  non-AGA  machines only #fmode()   and  #loressprites  are
allowed More docu'1lentation,  examples and fixes will be published soon for
creating displays

CreateDisplay CopList#[,CopList#..]

CreateDisplay  is used to setup a new screen display with  the  new  display
library  Any number of CopLists can be passed to CreateDisplay  although  at
present  they  must  be  in  order  of vertical  position  and  not  overlap
CreateDisplay  then  links the Copl.ists together using  internal  pointers.
bitmaps, colours and sprites attached to coplists are not affected

DisplayBitMap CopLis t#, bmap[,x, y] [, bmap[,x, y]]

The  DisplayBitMap command is similar in usage to the slice libraries'  show
commands  Instead  of different commands for front and back  playfields  and
smooth  scroll  options  there is only the one  DisplayBitMap  command  with
various parameter options With AGA machines,  the x positioning of lores and
hires  coplists uses the fractional part of the x parameter for super smooth
scrolling  The  CopList must be initialised with the smooth  scrolling  flag
set if the x,y parameters are used, same goes tor dualplayfield.

DisplaySprite CopList#,Sprite#,X, Y,Sprite Channel

DisplaySprite  is sitnilar to the slice libraries ShowSprite  cotnmand  with
the  added  advantage  of  super hires positioning  and  extra  wide  sprite
handling. See also SpriteMode and the Usage discussion above.

DisplayPalette CopList#,Palette# [, coloroffset]

DisplayPalette copies colour information frotn a Palette to the CopList
specified.

Page 136


DisplayControls CopList#, BPL CON2, BPLCON3, BPL CON4

DisplayControls allows access to the more remote options  available  in  the
Amiga's display system. The following are the most important bits from these
registers (still unpublished by Commodore!*()@GYU&^)

The  default  values are given at the top of the table,  the parameters  are
exclusive or'd with these values.

To  set all the sprite color offsets to I so that sprite colours are fetched
from  color  registers  24()..255   instead  of  16..31  we  would  use  the
parameters: DisplayControls 0,0,0,$ee

Bit#        BPLCON2            BPLCON3                            BPLCON4
            ($224)            ($c00)                            ($11)
15            *            BANK2 *activecolorbank            BPLAM7 ;xorithbitplane
14            ZDBPSEL2        BANK1 *                            BPLAM6 ;DMA altering
13            ZDBPSEL1        BANK0 *                            BPLAM5 ;effectivecolour
12            ZDBPSEL0        PF20F2 coloffset pfield 2        BPLAM4 ;look up
11            ZDBPEN            PF20F1                            BPLAM3
10            ZDCTEN            PF20F0                            BPLAM2
09            KILLEHB *        LOCT *palette hi/lo nibble        BPLAM1
08            RDRAM=0 *                                        BPLAM0
07            SOGEN            SPRESI *sprite res                ESPRM7 high order color
06            PF2PRI H        SPRES0 *                        ESPRM6 offset tor even
05            PF2P2            BRDRBLANK border                ESPRM5 sprites
04            PF2P1            BRDNTRAN zd=border                ESPRM4
03            PFIP0                                            OSPRM7 hiorder color
02            PFIP2            ZDCLCKEN zd= 14mhz                OSPRM6 offset for odd
01            PFIPI            BRDSPRT spritesinborders!        OSPRM5 sprites
00            PFIPO            EXTBLKEN blank output?            OSPRM4


! = Don't touch
H -See standard hardware reference manual
* - controlled by display library
ZD - any reference to ZD is only a guess (just sold my genlock)

DisplayAdjust CopList#,fetchwid,dUfstrt,dUfstop,diwstrt,diwstop

Temporary control of display registers until I get the widthadjust parameter
working  with  InitCopL.ist.  Currently only  standard  width  displays  are
available but you can modify the width manually (just stick a screwdriver in
the  back of your 1084)  or with some knowledge of Commodores AGA circuitry.
Ha  ha  ha.   No  to be quite serious I really do not have a clue  how  they
cludeged  up  the  Amiga  chip set.  When ECS was  introduced  suddenly  all
display fetching moved to the right.  Now they seem to have done the same to
sprites  so  it  is near impossible to have them all going without  limiting
yourself to a seriously thin display.

If  you  hack  around with the system copperlists you'll find they  actually
change fetch modes as you scroll a viewport across the display and

Page 137

commodore say you should not use sprites anyway so as to be compatible  with
their new hardware which is rumoured to run WindowsNT,  yipeee.  By then  we
will  be  hopefully  shipping the Jaguarlib  for  Blitz.   (close  than  you
think)...

CustomColors CopList#, CCOffset, YPos,Palette,startcol,numcols

Using  the  custom copper space in a display,  CustomColors will  alter  the
displays  palette at the given YPos.  The number of customcops  required  is
either 2+numcols for ecs displays and 2+n+n+n/16 for age displays.  In  age,
numcols must be a multiple of 32.

Note that large AGA palette changes may take several lines of the display to
be complete.

CustomStri ng CopList#, CCOffset, YPos, Copper$

CustomString allows the user to insert their own copper commands  (contained
in  a  string)  into the display's copper list at a given vertical position.
The  atnount of space required is equal to the number of copper instructions
in  the Copper$ (length of string divide by 4)  plus 2 which of course  have
to be allocated with InitCopList before CustomString is used.

CustomSprites Coplist#, CCOffset, YPos, NumSprites

CustomSprites inserts a copper list that reinitialises the sprites  hardware
at  a  certain  vertical position in the display.  These lower  sprites  are
assigned sprite numbers of 8..15. CustomCops required = 4 x numsprites + 2

DisplayDblScan mode

DisplayDblScan is used to divide the vertical resolution of the  display  by
2,4,8  or  16 using Modes 1,2,3 and 4.  This is most useful for fast  bitmap
based zooms. A Mode of 0 will return the display to 100% magnification.

As  with  the  DisplayRainbow,  DisplayRGB,  DisplayUser  and  DisplayScroll
commands  DisplayDblScan uses the new line by line  copper  control  of  the
display library. To initialise this mode a negative parameter is used in the
CustotnCops parameter of the InitCopList command.  DisplayDblScan requires 2
copper instructions per line (make CustomCops=-2).

DisplayRai nbow CopList#, Register,Palettetcopoffset]

DisplayRainbow is used to alter a certain colour register vertically down  a
display.   It  simple  maps  each colour in a palette  to  the  coresponding
vertical  position  of  the  display.    ECS  displays  require  one  copper
instruction per line while AGA displays require 4.

DisplayRGB CopList#,Pegister,line,r,g,bGcopoffset]

DisplayRGB  is  a  single  line  version   of  DisplayRainbow  allowing  the
programmer  to  alter  any  register   of  any  particular  line.   As  with
DisplayRainbow ECS displays require I copper instruction while AGA  requires
4.

Page 138

DisplayUser CopList#, Line,Stringt Offset]

DisplayUser allows the programmer to use their own Copper$ at  any  line  of
the  display.  Of course copper instructions have to be allocated  with  the
number of copper instructions in the InitCoplist multiplied by - 1.

DisplayScrol l CopList#, &xpos. q(n), &xpos.q(n)[, Offset]

DisplayScroll allows the program to dynamically display any part of a bitmap
on  any  line  of  the  display.  DisplayScroll  should  always  follow  the
DisplayBitMap  command.  The parameters are two arrays  holding  a  list  of
xoffsets that represent the difference in horizontal position from the  line
above.   AGA machines are able to use the fractional part of each entry  for
super  hiresolution positioning of the bitmap.  Three instructions per  line
are required for the DisplayScroll command.

Page 139

R-12: BLITZMODE IO COMMANDS

This  sections  refers to various Input/Output commands available  in  Blitz
mode.

It should be noted that although the Joyx,  Joyy,  Joyr,  and Joyb functions
do  not  appear  here,  they are still available in  Blitz  mode  (yes  your
honour).

BlikKeys Onl Off

BlitzKeys is used to turn on or off Blitz mode keyboard reading.   If  Blitz
mode  keyboard reading is enabled,  the Inkey$ function may be used to  gain
information about keystrokes in Blitz mode.

BlikQualifier

BlitzQualifier returns any qualifier keys that were held down in combination
with the last inkey$ during BlitzMode input.

BlikRepeat Delay,Speed

BlitzRepeat  allows  you  to determine key repeat characteristics  in  Blitz
mode.  Delay specifies the amount of time,  in fiftieths of a second, before
a  key will start repeating.  Speed specifies the amount of time,  again  in
fiftieths  of  a  second,  between repeats of a  key  once  it  has  started
repeating.

BlitzRepeat  is  only  effective when the Blitz  mode  keyboard  reading  is
enabled. This is done using the BlitzKeys command.

RawStatus (Rawkey)

The  RawStatus  function can be used to determine if an  individual  key  is
being held down or not.  Rawkey is the rawcode of the key to check for.   If
the specified key is being held down, a value of -I will be returned. If the
specified key is not being held down, a value of zero will be returned.

RawStatus is only available if Blitz mode keyboard reading has been enabled.
This is done using the BlitzKeys command.

Mouse On| Off

The  Mouse  command turns on or off Blitz mode's ability to read the  mouse.
Once  a  Mouse On has been executed,  programs can read the mouse's position
or speed in Blitz mode.

Pointer Sprite#,Sprite Channel

The  Pointer  command allows you to attach a sprite object  to  the  mouse's
position in the currently used slice in Blitz mode.

To properly attach a sprite to the mouse position,  several commands must be
executed in the correct sequence.  First, a sprite must be created using the
LoadShape  and  GetaSprite sequence of commands.  Then,   a  slice  must  be
created to display the sprite in.

A Mouse On must then be executed to enable mouse reading.

Page 140

MouseArea Minx,Miny,Maxx,Maxy

MouseArea  allows you to limit Blitz mode mouse movement  to  a  rectangular
section  of  the display.  Minx and Miny define the top left corner  of  the
area, Maxx and Maxy define the lower right corner.

MouseArea defaults to an area from 0,0 to 320,200.

MouseX

If  Blitz mode mouse reading has been enabled using a Mouse On command,  the
MouseX function may be used to find the current horizontal location  of  the
mouse.   If  mouse reading is enabled,  the mouse position will  be  updated
every  fiftieth of a second,  regardless of whether or not a  mouse  pointer
sprite is attached.

MouseY

If  Blitz mode mouse reading has been enabled using a Mouse On command,  the
MouseY  function may be used to find the current vertical  location  of  the
mouse. If mouse reading is enabled, the mouse position will be updated every
fiftieth of a second, regardless of whether or not a mouse pointer sprite is
attached.

MouseXSpeed

If  Blitz mode mouse reading has been enabled using a Mouse On command,  the
MouseXSpeed  function may be used to find the current  horizontal  speed  of
mouse  movement,  regardless of whether or not a sprite is attached  to  the
mouse.

If  MouseXSpeed returns a negative value,  then the mouse has been moved  to
the left.  If a positive value is returned,  the mouse has been moved to the
right.

MouseXSpeed  only  has  relevance after every  vertical  blank.   Therefore,
MouseXSpeed should only be used after a VWait has been executed,  or  during
a vertical blank interupt.

MouseYSpeed

If  Blitz mode mouse reading has been enabled using a Mouse On command,  the
MouseYSpeed  function  may be used to find the  current  vertical  speed  of
mouse  movement,  regardless of whether or not a sprite is attached  to  the
mouse.

If  MouseYSpeed  returns a negative value,  then the mouse  has  been  moved
upwards.   If  a  positive  value is returned,  the  mouse  has  been  moved
downwards.

MouseYSpeed  only  has  relevance after every  vertical  blank.   Therefore,
MouseYSpeed should only be used after a VWait has been executed,  or  during
a vertical blank interupt.

LoadBlitzFont BlitzFont#,Fontname.font$

LoadBlitzFont  creates  a  blitzfont object.  Blitzfonts  are  used  in  the
rendering  of  text to bitmaps.  Normally,  the standard rom resident  topaz
font is used to render text to

Page 141

bitmaps. However, you may use LoaclBlitzFont to select a font of your choice
for bitmap output.

The  specified Fontname.font$ parameter specifies the name of  the  tont  to
load, which MUST be in your FONTS: directory.

I  oadBlitzFont  may  only  be used to load eight by eight  non-proportional
fonts.

Use BlitzFont BlitzFont#

If  you htLvc loaded two or more blitzfont objects using LoadBlitzFont,  Use
Blitzl;ont  may  be  used  to select one of these fonts  for  future  bitmap
output.

Free BlitzFont BlitzFont#

Free  BlitzFont 'unlotLds' a previously loaded blitzfont object.  This frees
up any memory occupied by the font.

BitMapOutput BitMap#

BitMapOutput may be used to redirect Print statements to be rendered onto  a
bitmap.   The  font  used for rendering may be altered using  LoadBlitzFont.
Fonts used for bitmap output must be eight by eight non-proportional fonts.

BitMapOutput  is mainly of use in Blitz mode,  as.other forms  of  character
output become unavailable in Blitz mode.

Colour Foreground Colour[,Background Colour]

Colour  allows  you  to  alter the colours use to render  text  to  bitmaps.
Foreground colour allows you to specify the colour text is rendered in,  and
the  optional Background colour allows you to specify the colour of the text
background.

The palette used to access these colours will depend upon whether you are in
Blitz  mode  or in Amiga mode.  In Blitz mode,  colours will come  from  the
palette of the currently used slice.  In Amiga mode,  colours will come from
the palette of the screen the bitmap is attached to.

Locate X, Y

If  you are using BitMapOutput to render text,  Locate allows you to specify
the cursor position at which characters are rendered.

X  specifies a character position across the bitmap,  and is always  rounded
down to a multiple of an eighth.

Y  specifies a character position down the bitmap,  and may be a  fractional
value.   For example,  a Y of 1.5 will set a cusor position one and  a  half
characters down from the top of the bitmap.

CursX

When  using BitMapOutput to render text to a bitmap,  CursX may be  used  to
find  the horizontal character position at which the next character  Printed
will appear.

CursX  will reflect the cursor position of the bitmap specified in the  most
recently executed BitMapOutput statement.

Page 142

CursY

When  using BitMapOutput to render text to a bitmap,  CursY may be  used  to
find  the  vertical  character position at which the next character  Printed
wil1 appear.  CursY will reflect the cursor position of the bitmap specified
in the most recently executed BitMapOutput statement.

BitMapinput

BitMaplnput  is a special command designed to allow you  to  use  Edit$  and
Edit  in  Blitz  mode.  To work properly,  a BlitzKeys  On  must  have  been
executed  before BitMapInput.  A BitMapOutput must also be  executed  before
any Edit$ or Edit commands are encountered.

Page 143

R-13: BITMAP COMMANDS

Blitz  BitMap  objects  are  used primarily for  the  purpose  of  rendering
graphics.   Most  commands in Blitz for generating graphics  (excluding  the
Window and Sprite commands) depend upon a currently used BitMap.

BitMap objects may be created in one of two ways. A BitMap may be created by
using the BitMap command,  or a BitMap may be 'borrowed' from a Screen using
the ScreensBitMap command.

BitMaps  have  three main properties.  They have a width,  a  height  and  a
depth.   If  a  BitMap  is created using the ScreensBitMap  command,   these
properties  are taken from the dimensions of the Screen.   If  a  BitMap  is
created using the BitMap command, these properties must be specified.

BitMap BitMap#, Width,Height,Depth

BitMap creates and initializes a bitmap object.  Once created, the specified
bitmap becomes the currently used bitmap.  Width and Height specify the size
of  the  bitmap.   Depth specifies how many colours may be  drawn  onto  the
bitmap,   and  may  be  in the range one through six.   The  actual  colours
available  on  a  bitmap can be calculated using 2^depth.  For  example,   a
bitmap of depth three allows for 2^3 or eight colours.

Use BitMap BitMap#

Use  BitMap defines the specified bitmap object as being the currently  used
BitMap.   This is necessary for commands,  such as Blit,  which require  the
presence of a currently used BitMap.

Free BitMap BitMap#

Free  BitMap erases all information connected to the specified bitmap.   Any
memory  occupied by the bitmap is also deallocated.  Once free'd,  a  bitmap
may no longer be used.

CopyBitMap BitMap#,BitMap#

CopyBitMap  will make an exact copy of a bitmap object into  another  bitmap
object.   The  first BitMap# parameter specifies the source bitmap  for  the
copy, the second BitMap# the destination.

Any graphics rendered onto the source bitmap will also be copied.

ScreensBitMap Screen#,BitMap#

Blitz  allows  you the option of attaching a bitmap object to any  Intuition
Screens you open.  If you open a Screen without attaching a bitmap, a bitmap
will  be  created  anyway.   You  may   then  find  this  bitmap  using  the
ScreensBitMap command.  Once ScreensBitMap is executed, the specified bitmap
becomes the currently used bitmap.

Page 144

LoadBitMap BitMap#,Filename$[,Palette#]

LoadBitMap  allows  you  to  load an ILBM  IFF  graphic  into  a  previously
initialized bitmap object.  You may optionally load in the graphics's colour
palette  into  a  palette object specified by Palette#.  An  error  will  be
generated if the specified Filename$ is not in the correct IFF format.

SaveBitmap BitMap#, Filename$t Palette#]

SaveBitMap  allows  you to save a bitmap to disk in  ILBM  IFF  format.   An
optional palette may also be saved with the IFF.

BitPlanesBitMap SrcBitMap, DestBitMap, PlanePick

BitPlanesBitMap creates a 'dummy' bitmap from the SrcBitMap  with  only  the
bitplanes specified by the PlanePick mask. This is useful for shadow effects
etc.   where  blitting speed can be speed up because of the fewer  bitplanes
involved

ShapesBitMap Shape#,BitMap#

ShapesBitMap  creates  a  dummy  BitMap so  drawing  commands  can  be  used
directly on a shapes image data.

CludgeBitMap BitMap#, Width,Height,Depth,Memory

CludgeBitMap  will  create a bitmap object with  the  proportions  for  that
specified using the memory location given.  Of course,  the memory  location
specified  must  be  in  chipmem and it is upto  the  user  to  ensure  that
sufficient memory has been allocated.  This command is most useful for games
where memory fragmentation can be a big problem,  by allocating one block of
memory  on program initialisation for all bitmaps CludgeBitMap can  be  used
so that creating and freeing of BitMaps is not necessary.

BitMapWindow srobitmap#,destbitmap#,x,y,w,h

BitMapWindow creates a dummy bitmap inside another bitmap.   Both  x  and  w
parameters  are  rounded to the nearest 16 pixel boundary.   Any  rendering,
printing  and  blitting to the new bitmap will be clipped  inside  the  area
used.

BitMapOrigin BitMapOrigin BitMap#,x,y

BitMapOrigin  allows the programmer to relocate the  origin  (0,0)   of  the
bitmap used by the drawing commands line, poly, box and circle.

Decodel LB M DecodelLBM BitMap#,MemoryLocation

A very fast method of unpacking standard iffilbm data to a bitmap.  Not only
does  this command allow a faster method of loading standard IFF  files  but
allows  the  programmer to "incbin" iff pictures in their  programs.See  the
discussion above for using DecodeILBM on both files and included memory.

Page 145

R-14: 2D DRAWING COMMANDS

This section covers all commands related to rendering arbitrary graphics  to
bitmaps

All  commands  perform  clipping - that is,  they  all  allow  you  to  draw
'outside' the edge.s of bitmaps without grievous bodily harm being  done  to
the Amiga's memory

Cls [Colour]

Cls  allows you to fill the currently used bitmap with the colour  specified
by  the  Colour parameter.  If Colour is omitted,  the currently used bitmap
will  be  filled with colour ().  A Coltiur parameter of - I will cause  the
entire bitmap to be 'inverted'.

Plot X, Y,Colour

Plot  is  used  to alter the colour of an individual pixel on the  currently
used bitmap.  X and Y .specify the location of the pixel to be altered,  and
Colour specifies the colour to change the pixel to.  A Colour parameter of -
I will cause the pixel at the specified pixel position to be 'inverted'.

Point (X,Y)

The  Point  function  will return the colour of a particular  pixel  in  the
currently used hitmap.  The pixel to be examined is specified by the X and Y
parameters  If X and Y specify a point outside the edges of the  bitmap,   a
value of - I will be returned.

Line [X1, Y1,]X2, Y2,Colour

The  Lhie command draws a line connecting two pixels onto the currently used
bitmap.  The X and Y parameters specify the pixels to be joined,  and Colour
specifies the colour to draw the line in If Xl and Yl are omitted,  the  end
points (X2,Y2) of the last line drawn will be used. A Colour parameter of -I
will cause an 'inverted' line to be drawn

Box X1, Y1,X2, Y2, Colour

The  Box command draws a rectangular outline onto the currently used bitmap.
X  I,   Y  I,  X2 and Y2 specify two corners of the box to be drawn.  Colour
refers  to  the colour to draw the box in.  A Colour parameter  of  -I  will
cause an 'inverted' box to be drawn.

Boxf X1, Y1,X2, Y2, Colour

Boxf draws a solid rectangular shape on the currently used bitmap.  Xl,Yl,X2
and Y2 refer to two corners of the box.  Colour specifies the colour to draw
the box in.  A Colour parameter of -I will cause the rectangular area to  be
'inverted'.

Circle X, Y,Radius[, Y Radius],Colour

Circle will draw an open circle onto the currently used bitmap. X and Y

Page 146

specify  the  mid point of the circle.  The Radius parameter  specifies  the
radius of the circle.  If a Y Radius parameter is supplied,  then an ellipse
may  be drawn.  A Colour parameter of -l will cause an 'inverted' circle  to
be drawn.

Circlet X, Y,Radius[, Y Radius],Colour

Circlef will draw a filled circle onto the currently used bitmap.  X  and  Y
specify the mid point of the circle - Colour,  the colour in which  to  draw
the circle.  The Radius parameter specifies the radius of the circle. If a Y
Radius parameter is supplied, then an ellipse may be drawn.

A Colour parameter of - l will cause an 'inverted' circle to be drawn.

Scroll X1, Y1, Width,Height,X2, Y2[,Source BitMap]

Scroll allows rectangular areas within a bitmap to be moved around.  Xl, Yl,
Width and Height specify the position and size of the rectangle to be moved.
X2 and Y2 specify the position the rectangle is to be moved to.

An  optional  Source BitMap parameter allows you to move  rectangular  areas
from one bitmap to another.

FloodFill X, Y, Colour G Border Colour]

FloodFill  will  'colour  in'  a  region  of  the  screen  starting  at  the
coordinates X,Y.  The first mode will fill all the region that is  currently
the  colour at the coordinates X,Y with the colour specified by Colour.  The
second  mode  will  fill  a region starting at X,Y  and  surrounded  by  the
BorderColour with Colour.

FreeFill

FreeFill will deallocate the memory that Blitz uses to execute the  commands
Circlef, FloodFill, ReMap and Boxf.

Blitz uses a single monochrome bitmap the size of the bitmap being drawn  to
to do it's filled routines, by using the FreeFill command this BitMap can be
'freed' up if no more filled commands are to be executed.

ReMap colour#O,colour#1[,Bitmap]

ReMap  is used to change all the pixels on a BitMap in one colour to another
colour.  The optional BitMap parameter will copy all the pixels in  Colour#O
to their new colour on the new bitmap.

Poly numpoints, *coords. w,color

Poly  is  a bitmap based commands such as Box and Line.  It draws a  polygon
using coordinates from an array or newtype of words.

Polyf numpoints, *coords. w,color[,color2]

Same  as  Poly  except  Polyf  draws filled polygons  and  has  an  optional
parameter  color2,  if used this colour will be used if the coordinates  are
listed in anti-clockwise order,  useful for 3D type applications. If color2=
-l  then  the  polygon is not drawn if the verticies  are  listed  in  anti-
clockwise order.

Page 147

R-15: ANIMATION SUPPORT COMMANDS

The  following  4 commands allow the display of standard IFF  animations  in
Blitz.   The  animation must be compatible with the DPaint 3  format,   this
method  uses  long  delta (type 2)  compression and  does  not  include  any
palette changes.

Anims  in  nature use a double buffered display,  with the addition  of  the
ShowBitMap command to Blitz we can now display (play)  Anims in  both  Blitz
and  Amiga  modes.  An Anim consists of an initial frame which needs  to  be
displayed (rendered)  using the InitAnim command, subsequent frames are then
played  by using the NextFrame command.  The Frames()  function returns  the
number of frames of.an Anim.

We have also extended the LoadShape command to support Anim brushes.

LoadAnim Anim#,FileName$[Palette#]

The  LoadAnim  command  will  create  an  Anim  object  and  load  a  DPaint
compatible animation.  The ILBMInfo command can be used to find the  correct
screensize  and  resolution  for  the  anim  file.   The  optional  Palette#
parameter can be used to load a palette with the anims correct colours.

InitAnim Anim#l,Bitmap#]

InitAnim  renders the first two frames of the Anim onto the  current  BitMap
and  the  BitMap  specified  by the second parameter.   The  second  BitMap#
parameter is optional,  this is to support Anims that are not in  a  double-
buffered  format  (each frame is a delta of the  last  frame  not  from  two
frames  ago).  However,  the two parameter double buffered form of  InitAnim
should always be used. (hmmm don't ask me O.K.!)

NextFrame Anim#

NextFrame  renders the nextframe of an Anim to the current BitMap.   If  the
last  frame  of an Anim has been rendered NextFrame will loop  back  to  the
start of the Animation.

Frames (Anim#)

The Frames() function returns the number of frames in the specified Anim.

Page 148

R-16: SHAPE HANDLING COMMANDS

Shape  objects  are used for the purpose of storing graphic  images.   These
images may be used in a variety of ways.  For example,  a shape may be  used
as the graphics for a gadget,  or as the graphics for a menu item or perhaps
an alien being bent on your destruction.

See  the Blitting section for the many commands that are available  for  the
purpose  of  drawing shapes onto bitmaps.  These commands  use  the  Amiga's
blister chip to achieve this, and are therefore very fast.

Note  that Blitz supports two different file formats for storage of  shapes.
Standard  IFF  brush  files  (such  as created  with  DPaint)   as  well  as
animbrushes  use  the  LoadShape/SaveShape commands  and  the  faster  Blitz
format uses the LoadShapes and SaveShapes format.

LoadShape Shape#,Filename$LPalette#]

LoadShape  allows  you to load an ILBM IFF file into a  shape  object.   The
optional  Palette#  parameter  lets you also  load  the  colour  information
contained in the file into a palette object.

The LoadShape command has now been extended to support anim brushes,  if the
file is an anim brush the shapes are loaded into consecutive shapes starting
with the Shape# provided.

SaveShape Shape#,Filename$,Palette#

SaveShape will create an ILBM IFF file based on the specified shape  object.
If you want the file to contain colour information,  you should also specify
a palette object using the Palette# parameter.

LoadShapes Shape#[, Shape#],Filename$

LoadShapes  lets you load a 'range' of shapes from disk  into  a  series  of
shape  objects.   The file specified by Filename$ should have  been  created
using the SaveShapes command.

The  first  Shape# parameter specifies the number of the first shape  object
to  be loaded.  Further shapes will be loaded into increasingly higher shape
objects.

If  a  second  Shape# parameter is supplied,  then only  shapes  up  to  and
including the second Shape# value will be loaded.  If there are  not  enough
shapes  in  the  file  to fill this range,  any excess  shapes  will  remain
untouched.

SaveShapes Shape#,Shape#,Filename$

SaveShapes allows you to create a file containing a range of shape  objects.
This file may be later loaded using the LoadShapes command.

The  range  of shapes to be saved is specified by Shape#,Shape#,  where  the
first  Shape#  refers to the lowest shape to be saved and the second  Shape#
the highest.

Page 149

GetaShape Shape#,X, Y, Width,Height

GetaShape lets you transfer a rectangular area of the currently used  bitmap
into the specified shape object.  X, Y, Width and Height specify the area of
the bitmap to be picked up and used as a shape.

CopyShape Shape#,Shape#

CopyShape  will produce an exact copy of one shape object in  another  shape
object. The first Shape# specifies the source shape for the copy, the second
specifies the destination shape.

CopyShape is often used when you require two copies of a shape in  order  to
manipulate (using, for example, XFlip) one of them.

AutoCookie Onl Off

When  shapes objects are used by any of the blitting routines (for  example,
Blit),   they usually require the presence of what is known as a'cookiecut'.
These  cookiecuts  are used for internal purposes by  the  various  blitting
commands, and in no way affect the appearance or properties of a shape. They
do, however, consume some of your valuable Chip memory.

When a shape is created (for example,  by using LoadShape or GetaShape),   a
cookiecut is automatically made for it.  However, this feature may be turned
off by executing an AutoCookie Off.

This  is a good idea if you are not going to be using shapes for blitting  -
for example, shapes used for gadgets or menus.

MakeCookie Shape#

MakeCookie  allows  you  to create a'cookiecut'  for  an  individual  shape.
Cookiecuts  are  necessary for shapes which are to be used  by  the  various
blitting commands (for example,  QBlit), and are normally made automatically
whenever a shape is created (for example,  using LoadShape). However, use of
the  AutoCookie  command may mean you end up  with  a  shape  which  has  no
cookiecut,   but which youi wish to blit at some stage.  You  can  then  use
MakeCookie to make a cookiecut for this shape.

ShapeWidth (Shape#)

The  ShapeWidth  function returns the width,  in pixels,   of  a  previously
created shape object.

ShapeHeight (Shape#)

The  ShapeHeight function returns the height,  in pixels,  of  a  previously
created shape object.

Handle Shape#,X,Y

All shapes have an associated 'handle'. A shape's handle refers to an offset
from  the  upper  left  of the shape to be used when  calculating  a  shapes
position  when it gets blitted to a bitmap.  This is also often referred  to
as a 'hot spot'.

The X parameter specifies the 'acrosswards' offset for a handle, the Y

Page 150

parameter specifies a 'downwards' offset.

Let's have a look at an example of how a handle works.  Assume you have  set
a shapes X handle to 5,  and it's Y handle to 10.  Now let's say we blit the
shape  onto a bitmap at pixel position 160,100.  The handle will  cause  the
upper  left  corner  of the shape to actually end up at 155,90,   while  the
point within the shape at 5,10 will end up at 160,100.

When  a  shape is created,  it's handle is automatically set to 0,0  -  it's
upper left corner.

MidHandle Shape#

MidHandle  will cause the handle of the specified shape to be  set  to  it's
centre. For example, these two commands achieve exactly the same result:

MidHandle O Handle O,ShapeWidth(O)/2,ShapeHeight(O)/2

For more information on handles, please refer to the Handle command.

XFlip Shape#

The  XFlip  command is one of Blitz's powerful shape manipulation  commands.
XFlip will horizontally 'mirror' a shape object,  causing the object  to  be
'turned back to front'.

YFlip Shape#

The  YFlip  command may be used to vertically 'mirror' a shape object.   The
resultant shape will appear to have been 'turned upside down'.

Scale Shape#,X Ratio, Y Ratio[,Palette#]

Scale  is  a very powerful command which may be used to 'stretch' or'shrink'
shape objects. The Ratio parameters specify how much stretching or shrinking
to  perform.  A Ratio greater than one will cause the shape to be  stretched
(enlarged), while a Ratio of less than one will cause the shape to be shrunk
(reduced).   A  Ratio  of exactly one will cause no change  in  the  shape's
relevant dimension.

As  there  are separate Ratio parameters for both x and y,  a shape  may  be
stretched along one axis and shrunk along the other!

The  optional Palette# parameter allows you to specify a palette object  for
use in the scaling operation.  If a Palette# is supplied,  the scale command
will use a 'brightest pixel' method of shrinking.  This means a shape may be
shrunk to a small size without detail being lost.

Rotate Shape#,Angle Ratio

The  Rotate  command  allows  you to rotate a  shape  object.   Angle  Ratio
specifies how much clockwise rotation to apply,  and should be in the  range
zero to one.  For instance,  an Angle Ratio of .5 will cause a shape  to  be
rotated 180 degrees,  while an Angle Ratio of .25 will cause a shape  to  be
rotated 90 degrees clockwise.

Page 151

DecodeShapes Shape#[,Shape#],MemoryLocation

DecodeShapes,  similar to DecodeMedModule ensures the data is  in  chip  and
then configures the Shape object(s) to point to the data.

InitShape Shape#, Width,Height,Depth

InitShape  has been added to simple create blank shape objects.  Programmers
who  make a habit of using ShapesBitMap to render graphics to a shape object
will appreciate this one for sure.

Page 152

R-17: BLITTING COMMANDS

The  process  of  putting a shape onto a bitmap using the blister  is  often
referred to as 'blitting' a shape.  The speed at which a shape is blitted is
important when you are writing animation routines,  as the smoothness of any
animation wil1 be directly affected by how long it takes to draw the  shapes
involved in the animation.

The two main factors which affect the speed at which a shape is blitted  are
it's size and the technique used to actually blit the shape.

This  section  will cover all commands which allow you to draw  shapes  onto
bitmaps using the Amiga's 'blister' chip.

Blit Shape#,X, Y[,Excessonoff]

Blit is the simplest of all the blitting commands.  Blit will simply draw  a
shape  object onto the currently used bitmap at the pixel position specified
by  X,Y.   The  shape's handle,  if any,  will be taken  into  account  when
positioning the blit.

The optional Excessonoff parameter only comes into use if you are blitting a
shape  which has less bitplanes (colours)  than the bitmap to  which  it  is
being  blitted.  In this case,  Excessonoff allows you to specify an  on/off
value for the excess bitplanes - ie,  the bitplanes beyond those altered  by
the  shape.   Bit zero of Excessonoff will specify an on/off value  for  the
first  excess  bitplane,   bit one an on/off value  for  the  second  excess
bitplane and so on.

The  manner  in which the shape is drawn onto the bitmap may be  altered  by
use of the BlitMode command.

BlitMode BLTCON0

The  BlitMode command allows you to specify just how the Blit  command  uses
the blister when drawing shapes to bitmaps.  By default,  BlitMode is set to
a tcookiemode' which simply draws shapes 'as is'.  However, this mode may be
altered to produce other useful ways of drawing.  Here are just some of  the
possible BLTCON0 parameters and their effects:

CookieMode:  Shapes are drawn 'as is'. EraseMode: An area the size and shape
of the shape willbe 'erased' on the destination bitmap.

InvMode:  An area the size and shape of the shape willbe 'inversed'  on  the
destination bitmap.  SolidMode:  The shape will be drawn as a solid area  of
one colour.

Actually,  these modes are all just special functions which return a  useful
value.   Advanced  programmers may be interested to know  that  the  BLTCON0
parameter  is  used by the Blit command's blister routine to  determine  the
blister MINITERM and CHANNEL USE flags.  Bits zero through seven specify the
miniterm,   and  bits  eight through eleven specify  which  of  the  blister
channels are used.  For the curious out there,  all the blister routines  in
Blitz assume the following blister channel setup:

Page 153



BlitterChannei Used For

    A    Pointer to shape's cookie cut
    B    Pointer to shape data
    C    Pointer to destination
    D    Pointer to destination

CookieMode

The  CookieMode function returns a value which may be used  by  one  of  the
commands involved in blitting modes.

Using  CookieMode  as  a blitting mode will cause  a  shape  to  be  blitted
cleanly, 'as is', onto a bitmap.

EraseMode

The  EraseMode  function  returns a value which  may  be  used  by  one  the
commands involved in blitting modes.

Using  EraseMode as a blitting mode will cause a blitted shape  to  erase  a
section of a bitmap corresponding to the outline of the shape.

InvMode

The  InvMode function returns a value which may be used by one the  commands
involved in blitting modes.

Using  InvMode as a blitting mode will cause a shape to 'invert'  a  section
of a bitmap corresponding to the outline of the blitted shape.

SolidMode

The  SolidMode  function  returns a value which  may  be  used  by  one  the
commands involved in blitting modes.

Using SolidMode as a blitting mode will cause a shape to overwrite a section
of a bitmap corresponding to the outline of the blitted shape.

Clueue Queue#,Max Items

The  Queue command creates a queue object for use with the QBlit and UnQueue
commands.  What is a queue? Well,  queues (in the Blitz sense)  are used for
the  purpose of multi-shape animation.  Before going into what a  queue  is,
let's have a quick look at the basics of animation.

Say you want to get a group of objects flying around the screen.  To achieve
this, you will have to construct a loop similar to the following:

Step l:  Start at the first object Step 2: Erase the object from the display
Step 3:  Move the object Step 4: Draw the object at it's new location on the
display Step 5:  If there are any more objects to move,  go on to  the  next
object and then go to step 2, else... Step 6: go to step l

Page 154



Step 2 is very important,  as if it is left out,  all the objects will leave
trails behind them!  However,  it is often very cumbersome to have to  erase
every  object  you wish to move.  This is where queues are  of  use.   Using
queues,  you can 'remember' all the objects drawn through a loop,  then,  at
the  end  of  the  loop (or at the start of the next loop),  erase  all  the
objects 'remembered' from the previous loop.  Lets have a look at  how  this
works:

Step l: Erase all objects remembered in the queue

Step 2:  Start at the first object Step 3:  Move the object Step 4: Draw the
object at it's new location,  and add it to the end of the queue Step 5:  If
there are any objects left to move,  go on to the next object,  then  go  to
step 3; else... Step 6: Go to step l

This  is  achieved  quite easily using Blitz's queue  system.   The  UnQueue
command performs step l, and the QBlit command performs step 4.

Queues  purpose  is to initialize the actual queue used to remember  objects
in.  Queue must be told the maximum number of items the queue is capable  of
remembering, which is specified in the Max Items parameter.

QBlit Queue#,Shape#,X, YLExcessonoff]

QBlit performs similarly to Blit,  and is also used to draw a shape onto the
currently used bitmap.  Where QBlit differs,  however,  is in that  it  also
remembers (using a queue)  where the shape was drawn,  and how big  it  was.
This allows a later UnQueue command to erase the drawn shape.

Please refer to the Queue command for an explanation of the use of queues.

The  optional  Excessonoff parameter works identically  to  the  Excessonoff
parameter  used by the Blit command.  Please refer to the Blit  command  for
more information on rhis parameter.

UnQueue Queue#[,BitMap#]

UnQueue is used to erase all 'remembered' items in a queue. Items are placed
in  a  queue by use of the QBlit command.  Please refer to Queue for a  full
explanation of queues and their usage.

An  optional BitMap# parameter may be supplied to cause items to  be  erased
by  way  of  'replacement' from another bitmap,  as opposed  to  the  normal
'zeroing out' erasing.

FlushQueue Queue#

FlushQueue  will force the specified queue object to be 'emptied',   causing
the next UnQueue command to have no effect.

QBlitMode BLTCON0

QBlitMode  allows  you  to control how the blister operates  when  QBlitting
shapes  to bitmaps.  Please refer to BlitMode for more information  on  this
command.

Page 155

Buffer Buffer#,Memorylen

The Buffer command is used to create a buffer object. Buffers are similar to
queues in concept,  but operate slightly differently.  If you have  not  yet
read the description of the Queue command,  it would be a good idea to do so
before continuing here.

The buffer related commands are very similar to the queue related commands -
Buffer,  BBlit,  and UnBuffer,  and are used in exactly the same way.  Where
buffers  differ  from  queues,  however,  is in their  ability  to  preserve
background  graphics.   Whereas  an UnQueue  command  normally  trashes  any
background graphics,  UnBuffer will politely restore whatever the BBlits may
have overwritten.  This is achieved by the BBlit command actually performing
two bliss.

The first blit transfers the area on the bitmap which the shape is about  to
cover  to  a  temporary storage area - the second blit  actually  draws  the
shape  onto  the bitmap.  When the time comes to UnBuffer all those  BBlits,
the  temporary  storage  areas will be transferred  back  to  the  disrupted
bitmap.

The Memorylen parameter of the Buffer command refers to how much memory,  in
bytes,   should  be put aside as temporary storage for the  preservation  of
background graphics.  The value of this parameter varies depending upon  the
size  of  shapes  to be BBlited,  and the maximum number  of  shapes  to  be
BBlited between UnBuffers.

A  Memorylen of 16384 should be plenty for most situations,  but may need to
be increased if you start getting 'Buffer Overflow' error messages.

BBlit Buffer#,Shape#,X, YtExcessonoff]

The  BBlit  command is used to draw a shape onto the currently used  bitmap,
and preserve the overwritten area into a previously initialized buffer.  For
more information on how buffers work, please refer to the Buffer command.

The  optional  Excessonoff parameter works identically  to  the  Excessonoff
parameter  used by the Blit command.  Please refer to the Blit  command  for
more information on this parameter.

UnBuffer Buffer#

UnBuffer is used to 'replace' areas on a bitmap overwritten by a  series  of
BBlit commands.  For more information on buffers, please refer to the Buffer
command.

FlushBuffer Buffer#

FlushBuffer will force the specified buffer object to be 'emptied',  causing
the next UnBuffer command to have no effect.

BBlitMode BLTCON0

BBlitMode  allows  you  to control how the blister operates  when  BBlitting
shapes  to bitmaps.  Please refer to BlitMode for more information  on  this
command.

Page 156

Stencil Stencil#,BitMap#

The Stencil command will create a stencil object based on the contents of  a
previously created bitmap. The stencil will contain information based on all
graphics  contained  in the bitmap,  and may be  used  with  the  SBlit  and
ShowStencil commands.

SBlit Stencil#,Shape#,X,Y[,Excessonoff]

SBlit works identically to the Blit command,  and also updates the specified
Stencil#. This is an easy way to render 'foreground' graphics to a bitmap.

SBlitMode BLTCONO

SBlitmode is used to determine how the SBlit command operates.  Please refer
to the BlitMode command tor more information on blitting modes.

ShowStencil Buffer#,Stencil#

ShowStencil  is  used  in  connection with BBlits  and  stencil  objects  to
produce a 'stencil' effect.  Stencils allow you create the effect of  shapes
moving  'between'  background  and   foreground  graphics.   Used  properly,
stencils can add a sense of 'depth' or'three dimensionality' to animations.

So what steps are involved in using stencils? To begin with, you need both a
bitmap  and a stencil object.  A stencil object is similar to  a  bitmap  in
that it contains various graphics.  Stencils differ,  however,  in that they
contain  no  colour information.  They simply determine where  graphics  are
placed on the stencil.  The graphics on a stencil usually correspond to  the
graphics representing 'foreground' scenery on a bitmap.

So  the first step is to set up a bitmap with both foreground and background
scenery on it.  Next,  a stencil is set up with only the foreground  scenery
on it.  This may be done using either the Stencil or SBlit command.  Now, we
BBlit our shapes.  This will,  of course,  place all the shapes in front  of
both  the background and the foreground graphics.  However,  once all shapes
have  been  BBlitted,   executing the ShowStencil command  will  repair  the
damage done to the foreground graphics!

Block Shape#,X, Y

Block  is  an  extremely  fast  version   of  the  Blit  command  with  some
restrictions.  Block should only be used with shapes that are 16,32,48,64...
pixels  wide and that are being blitted to an x position of 0,16,32,48,64...
Note  that the height and y destination of the shape are not limited by  the
Block command.

Block is intended tor use with map type displays.

BlitColl (Shape#,x,y)

BlitColl is a fast way of collision detection when blitting shapes. BlitColl
returns - I if a collision occurs,  O if no collision. A collision occurs if
any  pixel  on  the current BitMap is non zero where your shape  would  have
been blitted.

ShapesHit  is  faster  but less accurate as it checks only  the  rectangular
area  of each shape,  where as BlitColl takes into account the shape of  the
shape and of course can not tell you what shape you have collided with.

Page 157

ClipBlit ClipBlit Shape#,X, Y

ClipBlit  is  the  same as the Blit command except ClipBlit  will  clip  the
shape to the inside of the used bitmap,  all blit commands in Blitz are  due
to be expanded with this feature.

ClipBlitMode BPLCON0

Same  as BlitMode except applies to the ClipBlit command.  Another oversight
now fixed.

BlockScroll X1, Y1, Width,Height,X2, Y2[,BitMap#]

Same  as the Scroll command except that BlockScroll is much faster but  only
works with 16 bit aligned areas.  This means that Xl,  X2 and Width must all
be  multiples  of 16.  Useful for block scrolling routines that  render  the
same blocks to both sides of the display,  the programmer can now choose  to
render  just  one set and then copy the result to the other  side  with  the
BlockScroll command.

Page 158

R-18: SPRITE HANDLING COMMANDS

Sprites  are another way of producing moving objects on the Amiga's display.
Sprites are,  like shapes, graphical objects. However unlike shapes, sprites
are  handled  by  the Amiga's hardware completely separately  from  bitmaps.
This  means  that sprites do not have to be erased when it's  time  to  move
them,   and that sprites in no way destroy or interfere with bitmap graphics
Also,   once  a sprite has been displayed,  it need not be referenced  again
until it has to be moved.

In this release of Blitz,  sprites are only available in Blitz mode and have
either 3 or 15 colours (2 or 4 bitplanes).  Each slice may display a maximum
of  up  to 8 sprites.  Other conditions may lower this maximum such  as  the
width,  depth and resolution of the slice.  The Amiga hardware has 8  sprite
channels,   standard 16 wide 3 colour sprites require a single channel,   15
colour  sprites  need  two  and sprites wider than  16  will  require  extra
channels  also.   15 color sprites must use an even numbered  channel,   the
subsequent odd channel then becomes unavailable.

Sprites  also  require  a  special colour palette set  up.   Fifteen  colour
sprites  take their RGB values from colour registers 17 through  31.   Three
colour  sprites,   however,  take on RGB values depending  upon  the  sprite
channels  being  used  to  display them.  The following  table  shows  which
palette registers at'fect which sprite channels:

Sprite Channel            Colour Registers
0,1                    17-19
2,3                    21 -23
4,5                    25-27
6,7                    29-31

GetaSprite Sprite#,Shape#

To be able to display a sprite,  you must first create a sprite object. This
will contain the image information for the sprite.  GetaSprite will transfer
the  graphic  data contained in a shape object into a sprite  object.   This
allows  you  to  perform  any of the Blitz shape manipulation  commands  (eg
Scale or Rotate) on a shape before creating a sprite from the shape.

Once  GetaSprite has been executed,  you may not require  the  shape  object
anymore.  In this case,  it is best to t'ree up the shape object (using Free
Shape) to conserve as much valuable chip memory as possible.

ShowSprite Sprite#,X, Y,Sprite Channel

ShowSprite is the command used to actually display a sprite through a sprite
channel.   X  and Y specify the position the sprite is to be  displayed  at.
These  parameters are ALWAYS given in lo-resolution pixels.  Sprite  Channel
is  a value 0 through 7 which decides which sprite channel the sprite should
be display through.

InFront Sprite Channel

A feature of sprites is that they may be displayed either 'in front of' or

Page 159

'behind'  the  bitmap graphics they are appearing in.  The  InFront  command
allows you to determine which sprites appear in front of bitmaps,  and which
sprites appear behind.

Sprite  Channel  must be an even number in the range  0  through  8.   After
executing  an  InFront command,  sprites displayed through  sprite  channels
greater  than  or  equal  to Sprite Channel will appear  BEHIND  any  bitmap
graphics.  Sprites displayed through channels less than Sprite Channel  will
appear  IN  FRONT OF any bitmap graphics.  For example,  after executing  an
InFront 4,  any sprites displayed through sprite channels 4,5,6  or  7  will
appear  behind  any  bitmap graphics,  while any sprites  displayed  through
sprite channels 0,1,2 or 3 will appear in front of any bitmap graphics.

InFront should only be used in non-dualplayfield slices.

InFrontF Sprite Channel

InFrontF  is  used  on  dualplayfield slices to  determine  sprite/playfield
priority  with  respect to the foreground playfield.  Using combinations  of
InFrontF  and InFrontB (used for the background playfield),  it is  possible
to  display  sprites at up to 3 ditterent depths - some  in  front  of  both
playfields, some between the playfields, and some behind both playfields.

InFrontB Sprite Channel

InFrontB  is  used  on  dualplayfield slices to  determine  sprite/playtield
priority  with  respect to the background playtield.  Using combinations  of
InFrontB  and InFrontF (used tor the foreground playfield),  it is  possible
to  display  sprites at up to 3 different depths - some  in  front  of  both
playfields, some between the playfields, and some behind both playfields.

LoadSprites Sprite#[,Sprite#],Filename$

LoadSprites lets you load a 'range' of sprites from disk into  a  series  of
sprite  objects.  The file specified by Filename$ should have  been  created
using  the  SaveSprites command.  The first Sprite# parameter specifies  the
number  of  the first sprite object to be loaded.  Further sprites  will  be
loaded  into  increasingly  higher sprite  objects.   If  a  second  Sprite#
parameter  is  supplied,  then only sprites up to and including  the  second
Sprite# value will be loaded.  If there are not enough sprites in  the  file
to fill this range, any excess sprites will remain untouched.

SaveSprites Sprite#,Sprite#,Filename$

SaveSprites  allows  you  to  create a file containing  a  range  of  sprite
objects. This file may be later loaded using the LoadSprites command.

The range of sprites to be saved is specified by Sprite#,Sprite#,  where the
first  Sprite#  refers  to the lowest sprite to  be  saved  and  the  second
Sprite# the highest.

SpriteMode mode

For  use with the capabilities of the new Display library SpriteMode is used
to  define the width of sprites to be used in the program.  The mode  values
0, l and 2 correspong to the widths l 6, 32 and 64

Page 160

R-l9: COLLISION DETECTION COMMANDS

This section deals with various commands involved in the detection of object
collisions.

SetColl Colour,BitplanesLPlaylield]

There  are  3  different  commands  involved  in  controlling  sprite/bitmap
collision  detection,  of which SetColl is one (the other 2 being SetCollOdd
and  SetCollHi).  All three determine what colours in a bitmap will cause  a
collision with sprites.  This allows you to design bitmaps with  'safe'  and
'unsafe' areas.

SetColl  allows  you to specify a single colour which,  when  present  in  a
bitmap,  and in contact with a sprite,  will cause a collision.  The  Colour
parameter refers to the 'collidable' colour.  Bitplanes refers to the number
of bitplanes (depth) that bitmap collision are to be tested in.

The optional PlayField parameter is only used in a dualplayfield slice.   If
Playfield is 1,  then Colour refers to a colour in the foreground bitmap. If
Playfield is 0, then Colour refers to a colour in the background bitmap.

DoColl  and  PColl  are  the  commands   used  for  actually  detecting  the
collisions.

SetCollOdd

SetCollOdd  is  used  to control the detection of sprite/bitmap  collisions.
SetCollOdd  will  cause  ONLY  the   collisions  between  sprites  and  'odd
coloured'  bitmap  graphics to be reported.  Odd  coloured  bitmap  graphics
refers  to  any  bitmap  graphics rendered in  an  odd  colour  number  (de:
1,3,5...).   This allows you to design bitmap graphics in such  a  way  that
even  coloured  areas  are 'safe' (de:  they will not  report  a  collision)
whereas odd colour areas are 'unsafe' (de: they will report a collision).

The  DoColl  and  PColl commands are used to detect the actual sprite/bitmap
collisions.

SetCollHi EJitPlanes

SetCollHi may be used to enable sprite/bitmap collisions between sprites and
the  'high half' colour range of a bitmap.  For example,  if you have  a  16
colour bitmap, the high half of the colours would be colours 8 through 15.

The BitPlanes parameter should be set to the number of bitplanes (depth)  of
the bitmap with which collisions should be detected.

Please  refer  to the SetColl command for more information on  sprite/bitmap
collisions.

DoColl

DoColl is used to perform sprite/bitmap collision checking.  Once DoColl  is
executed,   the  PColl  and/or SColl functions may  be  used  to  check  for
sprite/bitmap or sprite/sprite collisions.

Before DoColl may be used with PColl,  the type of bitmap collisions  to  be
detected  must have been specified using one of the SetColl,  SetCollOdd  or
SetCollHi commands.

Page 161

After executing a DoColl,  PColl and SColl will return the same values until
the next time DoColl is executed.

PColl (Sprite Channel)

The  PColl  function  may  be used to find out if a  particular  sprite  has
collided  with any bitmaps.  Sprite Channel refers to the sprite channel  of
the sprite you wish to check is being displayed through.

If  the specified sprite has collided with any bitmap graphics,  PColl  will
return a true (-l ) value, otherwise PColl will return false (O).

Before  using  PColl,  a DoColl must previously have been executed.   Please
refer to DoColl for more information.

SColl (Sprite Channel, Sprite Channel)

SColl  may  be  used to determine whether the 2 sprites currently  displayed
through  the specified sprite channels have collided.  If they have,   SColl
will return true (- l ),  otherwise SColl will return false (O).  DColl must
have been executed prior to using SColl.

ShapesHit (Shape#,X, Y,Shape#,X, Y)

The ShapesHit function will calculate whether the rectangular areas occupied
by  2  shapes overlap.  ShapesHit will automatically take the shape  handles
into  account.  If the 2 shapes overlap,  ShapesHit will return  true  (-l),
otherwise ShapesHit will return false (O).

ShapeSpriteHit (Shape#,X, Y,Sprite#,X, Y)

The  ShapeSpriteHit  function will calculate whether  the  rectangular  area
occupied by a shape at one position,  and the rectangular area occupied by a
sprite at another position are overlapped. If the areas do overlap,

ShapeSpriteHit  will  return  true (- l ),   otherwise  ShapeSpriteHit  will
return  false (O).  ShapeSpriteHit automatically takes the handles  of  both
the shape and the sprite into account.

SpritesHit (Sprite#,X, Y,Sprite#,X, Y)

The  SpritesHit  function  will  calculate  whether  the  rectangular  areas
occupied  by  2  sprites  overlap.  SpritesHit will automatically  take  the
sprite  handles  into account.  If the 2 sprites overlap,   SpritesHit  will
return true (- l ), otherwise SpritesHit will return false (O).

Care should be taken with the pronunciation of this command.

RectsHit (X1, Y1, Widthl,Height1,X2, Y2, Width2,Height2)

The  RectsHit  function  may  be  used  to  determine  whether  2  arbitrary
rectangular  areas  overlap.  If the specified  rectangular  areas  overlap,
RectsHit will return true (- l ), otherwise RectsHit will return false (O).

Care should be taken with the pronunciation of this command.

Page 162

R-20: PALETTE COMMANDS

Amiga  colours are represented as values for the three primary colours  red,
green  and  blue.  These values are combined as an RGB value.  Palettes  are
Blitz  objects  that  contain  a series of RGB  values  that  represent  the
colours used by the display.

Palette  information can be loaded from an IFF file  or  defined  using  the
PalRGB/AGAPalRGB commands.  Palettes can be assigned to screens  and  slices
with both the Use Palette and ShowPalette commands.

Many commands are available for manipulating the colours within a palette.

Colour  values  on  slices and screens can also be changed directly  without
the use of palettes using the RGB and AGARGB commands.

Load Pa lette Palette#, Filename$[, Palette Offset]

LoadPalette  creates and initializes a palette object.  Filename$  specifies
the  name  of an ILBM IFF file containing colour information.  If  the  file
contains  colour  cycling information,  this will also be  loaded  into  the
palette object.

An  optional Palette Offset may be specified to allow the colour information
to be loaded at a specified point (colour register)  in the palette. This is
especially  useful in the case of sprite colours,  as these  must  begin  at
colour register sixteen.

LoadPalette does not actually change any display colours.  Once a palette is
loaded, Use Palette can be used to cause display changes.

ShowPalette Palette#

ShowPalette  replaces  Use Palette for copying a palette's  colours  to  the
current Screen or Shce.

Use Palette Palette#

Use  Palette  transfers  palette information from  a  palette  object  to  a
displayable  palette.   If executed in Amiga mode,  palette  information  is
transferred into the palette of the currently used Screen.  If  executed  in
Blitz  mode,   palette information is transferred into the  palette  of  the
currently used Slice.

NewPaletteMode Onl Off

The  NewPaletteMode flag has been added for compatibility with  older  Blitz
programs.   By  setting NewPaletteMode to On the Use Palette command  merely
makes the specified palette the current object and does not try to copy  the
colour information to the current Screen or Slice.

Free Palette Palette#

Free  Palette  erases  all information in a palette  object.   That  Palette
object may no longer be Used or Cycled.

Page 163



SavePalette Palette#,FileName$

Creates a standard IFF "CMAP" file using the given Palette's colors.

CyclePalette Palette#

CyclePalette  uses  the  standard color cycling parameters  in  the  palette
object  to  cycle  the colors.  Unlike the Cycle command  which  copied  the
resulting  palette  to  the  current screen the  CyclePalette  command  just
modifies  the  palette object and can hence be used with  the  DisplayBitmap
command in the new Display library.

FadePalette SrcPaleffe#,DestPalette#, Brightness. q ;palettelib

FadePalette  multiplies all colours in a Palette by the Brightness  argument
and maces the result in the DestPalette.

lnitPalette Palette#,NumColors

InitPalette  simply  initialises a palette object to  hold  NumColors.   All
colors will be set to black.

DecodePalette Palette#,MemoryLocationt Palette Offset]

DecodePalette  allows  the  programmer   to   unpack  included  iff  palette
information to Blitz palette objects.

Pal RG B Palette#, Colour Register,Bed, Green,Blue

PalRGB  allows  you to set an individual colour register  within  a  palette
object.  Unless an RGB has also been executed, the actual colour change will
not come into effect until the next time ShowPalette is executed.

RGB Colour Register,Red,Green,Blue

RGB  enables you to set individual colour registers in a palette to  an  RGB
colour value.  If executed in Amiga mode,  RGB sets colour registers in  the
currently used screen.  If executed in Blitz Mode, RGB sets colour registers
in  the  currently used slice.  Note that RGB does not alter palette objects
in any

Red (Colour Register)

Red  returns  the  amount  of RGB red in a specified  colour  register.   If
executed  in  Amiga mode,  Red returns the amount of red  in  the  specified
colour  register of the currently used screen.  If executed in  Blitz  mode,
Red  returns  the  amount of red in the specified  colour  register  of  the
currently used slice.  Red will always return a value in the range  zero  to
fifteen.

Green (Colour llegister)

Green  returns the amount of RGB green in a specified colour  register.   If
executed  in Amiga mode,  Green returns the amount of green in the specified
colour  register of the currently used screen.  If executed in  Blitz  mode,
Green

Page 164

returns  the  amount  of  green  in the specified  colour  register  of  the
currently used slice.  Green will always return a value in the range zero to
fifteen.

Blue (Colour Register)

Blue  returns  the  amount of RGB blue in a specified colour  register.   If
executed  in  Amiga mode,  Blue returns the amount of blue in the  specified
colour  register of the currently used screen.  If executed in  Blitz  mode,
Blue  returns  the amount of blue in the specified colour  register  of  the
currently used slice.

Blue will always return a value in the range zero to fifteen.

AGARGB Colour Register,Red,Green,Blue

The  AGARGB  command is the AGA equivalent of the RGB command.   The  'Red',
'Green'  and  'Blue' parameters must be in the range O through  255,   while
'Colour  Register'  is  limited to the number of colours  available  on  the
currently used screen.

AGAPalRGB Palette#, Colour Register,Red,Green,Blue

The  AGAPalRGB  command  is  the  AGA  equivalent  of  the  PalRGB  command.
AGAPalRGB allows you to set an individual colour register within  a  palette
object. This command only sets up an entry in a palette object, and will not
alter the actual screen palette until a 'ShowPalette' is executed.

AGARed (colour register)

The  AGARed  function  returns the red component  of  the  specified  colour
register  within  the  currently used screen.  The returned  value  will  be
within the range O (being no red) through 255 (being full red).

AGAGreen (colour register)

The  AGAGreen  function returns the green component of the specified  colour
register  within  the  currently used screen.  The returned  value  will  be
within the range O (being no green) through 255 (being full green).

AGABlue (colour register)

The  AGABlue  function returns the blue component of  the  specified  colour
register  within  the  currently used screen.  The returned  value  will  be
within the range O (being no blue) through 255 (being full blue).

SetCycle Palette#, Cycle,Low Colour,High Colour [,Speed]

SetCycle  is  used  to configure colour cycling information  for  the  Cycle
command.   The low and high colours specify the range of colours  that  will
cycle.   You may have a maximum of 7 different cycles for a single  palette.
The optional parameter Speed specifies how quickly the colours will cycle, a
negative value will cycle the colours backwards.

Page 165



Cycle Palette#

Cycle  will cause the colour cycling information contained in the  specified
palette  to  be  cycled  on  the  currently  used  Screen.   Colour  cycling
information  is  created when LoadPalette is executed or with  the  SetCycle
command.

StopCycle  StopCycle  will halt all colour cycling started  with  the  Cycle
command

Fadeln Palette#[,RateLLow Colour, High ColourD

Fadein  will  cause the colour palette of the currently  used  slice  to  be
'faded  in'  from  black  up to the RGB values contained  in  the  specified
Palette#.

Rate# allows you to control the speed of the fade,  with 0 being the fastest
fade.   Low Colour and High Colour allow you to control which colour palette
registers are affected by the fade.

FadeOut Palette#LRatef Low Colour, High Colour]]

Fadeout  will  cause the colour palette of the currently used  slice  to  be
'faded out' from the RGB values contained in the specified Palette# down  to
black.

Rate# allows you to control the speed of the fade,  wilh 0 being the fastest
fade.   Low Colour and High Colour allow you to control which colour palette
registers are affected by the fade.

For  FadeOut to work properly,  the RGB values in the currently  used  slice
should be set to the specified Palette# prior to using FadeOut.

ASyncFade Onl Off

ASyncFade allows you control over how the FadeIn and FadeOut commands  work.
Normally,   FadeIn and FadeOut will halt program flow,  execute  the  entire
fade, and then continue program flow. This is ASyncFade Off mode.

ASyncFade On will cause FadeIn and FadeOut to work differently.  Instead  of
performing the whole fade at once,  the programmer must execute  the  DoFade
command to perform the neixt step of the fade.  This allows fading to  occur
in parallel with program flow.

DoFade

DoFade will cause the next step of a fade to be executed.  ASyncFade On, and
a FadeIn or FadeOut must be executed prior to calling DoFade.

The  FadeStatus  function may be used to determine  whether  there  are  any
steps of fading left to perform.

FadeStatus

FadeStatus  is used in conjunction with the DoFade command to  determine  if
any  steps  of fading have yet to be performed.  If a fade process  has  not
entirely finished yet (de:  more DoFades are required), then FadeStatus will
return true (-l).  If not, FadeStatus will return false (0). Please refer to
ASyncFade and DoFade for more information.

Page 166



PaletteRange Palette#,StartCol,EndCol,rO,gO,bO,r1,gl,b 1

PaletteRange  creates  a  spread of colors within  a  palette.   Similar  to
DPaint's  spread  function PaletteRange takes a start  and  end  colour  and
creates the color tweens between them.

DuplicatePalette SrcPalette#,DestPalette#

DuplicatePalette  simply creates a new Palette  which  exactly  matches  the
SrcPalette.

Page 167



R-21: SOUND MUSIC & SPEECH COMMANDS

Sound objects are used to store audio information.  This information can  be
taken  from an 8SVX IFF file using LoadSound,  or defined by hand through  a
BASIC  routine using InitSound and SoundData.  Once a sound is created,   it
may be played through the Amiga's audio hardware.

Blitz supports loading and playing of both soundtracker and medmodule  music
files.

The  Amiga  speech  synthesiser   is   also   accessible  from  Blitz.   The
narrator.device  has  been upgraded in 2.0 increasing  the  quality  of  the
speech.   With a bit of messing around you can have a lot of  fun  with  the
Amiga's 'voice'.

LoadSound Sound#,Filename$

LoadSound creates a sound object for later playback. The sound is taken from
an  8SVX IFF file.  An error will be generated if the specified file is  not
in the correct IFF format.

Sound Sound#,Channe/mask[, Vo/1[, Vo/2...p

Sound  causes  a  previously created sound object to be played  through  the
Amiga's  audio  hardware.  Channelmask specifies which of the  Amiga's  four
audio  channels the sound should be played through,  and should  be  in  the
range one through fifteen.

The following is a list of Channelmask values and their effect:

Mask    Channe|O    Channe|1    Channel2    Channel3
1    on            off            off            off
2    off            on            off            off
3    on            on            off            off
4    off            off            on            off
5    on            off            on            off
6    off            on            on            off
7    on            on            on            off
8    off            off            off            on
9    on            off            off            on
10    off            on            off            on
11    on            on            off            on
12    off            off            on            on
13    on            off            on            on
14    off            on            on            on
15    on            on            on            on

In the above table, any audio channels specified as 'off' are not altered by
Sound,   and any sounds they may have previously been playing  will  not  be
affected.

Page 168

The  Volx  parameters allow individual volume settings for  different  audio
channels.  Volume settings must be in the range zero through 64,  zero being
silence,  and 64 being loudest. The first Vol parameter specifies the volume
for  the  lowest numbered 'on' audio channel,  the second Vol for  the  next
lowest and so on.

For  example,   assume  you are using the following  Sound  command:   Sound
0,10,32, 16

The Channelmask of ten means the sound will play through audio channels  one
and three.  The first volume of 32 will be applied to channel one,  and  the
second volume of 16 will be applied to channel three.

Any Vol parameters omitted will be cause a volume setting of 64.

LoopSound Sound#,Channelmask[, Vol1[, Vol2...D

LoopSound  behaves  identically to Sound,  only the  sound  will  be  played
repeatedly.   Looping a sound allows for the facility  to  play  the  entire
sound just once,  and begin repeating at a point in the sound other than the
beginning.   This  information is picked up from the 8SVX  IFF  file,   when
LoadSound  is  used  to create the sound,  or from the offset  parameter  of
InitSound.

Volume Channelmask, Vol1[, Vol2...]

Volume allows you to dynamically alter the volume of an audio channel.  This
enables effects such as volume fades.  For an explanation of Channelmask and
Vol parameters, please refer to the Sound command.

InitSound Sound#,LengthLPeriod[, Repeatil

InitSound  initializes a sound object in preparation  for  the  creation  of
custom  sound data.  This allows simple sound waves such as sine  or  square
waves to be algorithmically created.  SoundData should be used to create the
actual wave data.

Length refers to the length,  in bytes,  the sound object is required to be.
Length MUST be less than 1 28K, and MUST be even.

Period allows you to specify a default pitch for the sound.  A period of 428
will cause the sound to be played at approximately middle 'C'.

Otfset  is used in conjunction with LoopSound,  and specifies a position  in
the  sound  at which repeating should begin.  Please refer to LoopSound  for
more information on repeating sounds.

SoundData Sound#,Offset,Data

SoundData  allows you to manually specify the waveform of  a  sound  object.
The  sound  object  should  normally  have  been  created  using  InitSound,
although altering IFF sounds is perfectly legal.

SoundData  alters  one  byte of sound data at the  specified  Offset.   Data
refers  to the actual byte to place into the sound,  and should  be  in  the
range -128 to +127.

PeekSound (Sound#,Offset)

PeekSound returns the byte of a sample at the specified offset of the  sound
object specified.

Page 169

DecodeSound Sound#,MemoryLocation

DecodeSound,  similar to the other new Decode commands allows the programmer
to include sound files within their program's object code.

SetPeriod Sound#,Period

This  command  allows the programmer to manually adjust the  period  of  the
sound object to change it's effective pitch.

DiskPlay Filename$, Channelmask[, Vol1[, Vol2...p

DiskPlay will play an 8SVX IFF sound file straight from disk.  This is ideal
for  situations  where you simply want to play a sample  without  the  extra
hassle  of loading a sound,  playing it,  and then freeing it.  The DiskPlay
command will also halt program flow until the sample has finished playing.

DiskPlay  usually  requires much less memory  to  play  a  sample  than  the
LoadSound,  Sound technique.  Also,  DiskPlay allows you to play samples  of
any  length,  whereas LoadSound only allows samples up to 128K in length  to
be loaded.

DiskBuffer Bufferlen

DiskBuffer  allows  you to set the size of the memory  buffer  used  by  the
DiskPlay command.  This Buffer is by default set to 1024 bytes,  and  should
not normally have to be set to more than this.

Reducing the buffer size by too much may cause loss of sound quality of  the
DiskPlay command.

If you are using DiskPlay to access a very slow device,  the buffer size may
have to be increased.

Filter Onl Off

Filter may be used to turn on or off the Amiga's low pass audio filter.

LoadModule Module#,Filename$

LoadModule  loads  in  from disk a soundtracker/noisetracker  music  module.
This module may be later played back using PlayModule.

Free Module Module#

Free  Module may be used to delete a module object.  Any memory occupied  by
the module will also be free'd.

PlayModule Module#

PlayModule  will  cause  a previously loaded soundtracker/noisetracker  song
module to be played back.

StopModule

StopModule will cause any soundtracker/noisetracker modules which may be

Page 170



currently playing to stop.

Load Med Mod u le MedModule# Name

The  LoadMedModule command loads any version 4 channel Octamed module.   The
following  routines support upto and including version 3 of  the  Amiganut's
Med standard.

The  number  of MedModules loaded in memory at one time is only  limited  by
the  MedModules maximum set in the Blitz Options requester.  Like any  Blitz
commands that access files LoadMedModule can only be used in AmigaMode.

StartMedModule MedModule#

StartMedModule is responsible for initialising the module including  linking
after  it is loaded from disk using the LoadMedModule command.  It can  also
be used to restart a module from the beginning.

PlayMed

PlayMed is responsible for playing the current MedModule,  it must be called
every  50th of a second either on an interupt (#5)  or after a  VWait  in  a
program loop.

StopMed

StopMed will cause any med module to stop playing.  This not only means that
PlayMed  will have no affect until the next StartMedModule but silences  the
audio  channels so they are not left ringing as is the effect  when  PlayMed
is not called every vertical blank.

JumpMed Pattern#

JumpMed will change the pattern being played in the current module.

SetMedVolume Volume

SetMedVolume  changes  the overall volume that the  Med  Library  plays  the
module,  all the audio channels are affected. This is most useful for fading
out music by slowly decreasing the volume from 64 to 0.

GetMedVolume Channel#

GetMedVolume  returns  the current volume setting  of  the  specified  audio
channel.  This is useful for graphic effects that you may wish  to  sync  to
certain channels of the music playing.

GetMedNote Channel#

GetMedNote returns the current note playing from the specified channel.   As
with  GetMedVolume this is useful for producing graphics effects  synced  to
the music the Med Library is playing.

Page 171

GetMedinstr Channel

GetMedInstr  returns  the current instrument playing through  the  specified
audio channel.

SetMedMask Channel Mask

SetMedMask  allows  the  user to mask out audio  channels  needed  by  sound
effects stopping the Med Library using them.

DecodeMedModule MedModule#,MemoryLocation

DecodeMedModule replaces the cludgemedmodule,  as med modules are not packed
but  used  raw,   DecodeMedModule simply checks to see the  memory  location
passed  is  in ChipMem (if not it copies the data to chip)  and  points  the
Blitz MedModule object to that memory.

. Speak string$

The  Speak command will first convert the given string to phonetics and then
pass  it  to the Narrator.Device.  Depending on the settings of the Narrator
device (see SetVoice) the Amiga will "speak" the string you have sent in the
familiar Amiga synthetic voice.

SetVoice rate,pitch,expression,sex, volume,frequency

SetVoice  alters the sound of the Amiga's speech synthsiser by changing  the
vocal characteristics listed in the parameters above.

Translate$ (string$)

Translate$()  returns the phonetic equivalent of the string for use with the
PhoneticSpeak command.

PhoneticSpeak phonetic$

PhoneticSpeak  is  similar to the Speak command but should  only  be  passed
strings  containing legal phonemes such as that produced by the Translate$()
function.

VoiceLoc

VoiceLoc  returns  a  pointer  to  the  internal  variables  in  the  speech
synthesiser that enable the user to access new parameters added to  the  V37
Narrator Device.  Formants as referred to in the descriptions are the  major
vocal  tracts  and are separated into the parts of speech that  produce  the
bass, medium and trebly sounds.

Page 172



R-22: SCREEN COMMANDS

The  following  section covers the Blitz commands  that  let  you  open  and
control Intuition based Screen objects.

Command Description

Screen  Screen#,Mode[,   TiUe$] Screen#,X,  Y,  Width,Height,Depth,   VMode,
Title$,Dpen,Bpen[BMap#]

Screen  will  open  an Intuition screen.  The are 2 formats  of  the  screen
command, a quick format, and a long format.

The  quick  format of the Screen commands involves 3 parameters  -  Screen#,
Mode and an optional Title$.

Screen# specifies the screen object to create.

Mode specifies how many bitplanes the screen is to have,  and should  be  in
the  range I through 6.  Adding 8 to Mode will cause a hi-res screen  to  be
opened,  as opposed to the default lo-res screen.  A hi-res screen may  only
have  from  I  to  4 bitplanes.  Adding 16 to Mode will cause an  interlaced
screen to be opened. 'lPitle$ allows you to add a title to the screen.

The  long  format of Screen gives you much more control over how the  screen
is opened.

The  VMode parameter refers to the resolution of the Screen,  add the values
together to make up the screenmode you require:

hires=$8000
ham=$200

superhires=$20
interlace=4

lores=0

ShowScreen Screen#

ShowScreen will cause the specified screen object to be moved to  the  front
of the display.

WbToScreen Screen#

WbToScreen  will assign the Workbench screen a screen object  number.   This
allows  you to perform any of the functions that you would normally  do  own
your own screens,  on the Workbench screen.  It's main usage is to allow you
to open windows on the Workbench screen.

After execution, the Workbench screen will become the currently used screen.
FindScreen Screen#[, Title$]

This  command will find a screen and give it an object number so it  can  be
referenced in your programs.  If Title$ is not specified,  then the foremost
screen is found and given the object number Screen#.  If the Title$ argument
is specified, then a screen will be searched for that has this name.

After  execution,  the found screen will automatically become the  currently
used screen.

Page 173

LoadSc reen Screen#, Fi lename$[, Palette#]

LoadScreen  loads  an IFF ILBM picture into the screen object  specified  by
Screen#. The file that is loaded is specified by Filename$.

You  can  also  choose to load in the colour palette  for  the  screen,   by
specifying  the optional Palette#.  This value is the object number  of  the
palette you want the pictures colours to be loaded into.  For the colours to
be used on your screen, you will have to use the statement.

SaveScreen Screen#,Filename$

SaveScreen will save a screen to disk as an IFF ILBM file.  The  screen  you
wish  to save is specified by the Screen#,  and the name of the file you  to
create is specified by Filename$.

SMouseX

SMouseX  returns the horizontal position of the mouse relative to  the  left
edge of the currently used screen.

SMouseY

SMouseY  returns the vertical position of the mouse relative to the  top  of
the current screen.

ViewPort (Screen#)

The  ViewPort  function  returns  the  location  of  the  specified  screens
ViewPort.   The ViewPort address can be used with graphics.library  commands
and the like.

ScreenPens active text,  inactive text,  hilight, shadow, acUve fill, gadget
fill

ScreenPens  configures  the  10 default pens  used  for  system  gadgets  in
WorkBench 2.0.  Any Screens opened after a ScreenPens statement will use the
pens defined.  This command will have no affect when used with Workbench 1.3
or earlier.

CloseScreen Screen#

CloseScreen has been added for convenience. Same as Free Screen but a little
more intuitive (especially for those that have complained about such matters
(yes we care)).

HideScreen Screen#

Move Screen to back of all Screens open in the system.

BeepScreen Screen#

Flash specified screen.

Page 174

MoveScreen Screen#,deltax,deltay

Move specified screen by specified amount.  Good for system friendly special
effects.

ScreenTags Screen#,Title$[&TagList]or[[,Tag,Data]...]

Full  access  to all the Amiga's new display resoutions is now available  in
Amiga  mode by use of the Screen Tags command.  The following  tags  are  of
most interest to Blitz programmers.

#Left=$ 80000021 :#Top=$80000022 :#Width=$80000023
#Height=$80000024:#Depth=$80000025:#DetailPen=$80000026
#BlockPen=$80000027
#Title=$80000028 :#Colors=$80000029 :#ErrorCode=$8000002A
#Font=$8000002B :#SysFont=$8000002C:#Type=$8000002D
#BitMap=$8000002E
#PubName=$8000002F:#PubSig=$80000030
#PubTask=$80000031 :#DisplayID=$80000032
#DClip=$80000033:#0verscan=$80000034
#S howTitle=$ 80000036:#Behi nd=$80000037 :#_Qu iet=$80000038
#AutoScroll=$80000039:#Pens=$8000003A
#FullPalette=$8000003B:#ColorMapEntries=$8000003C
#Parent=$8000003D :#Draggable=$8000003E
#Exclusive=$8000003F
#SharePens=$80000040:#BackFill=$80000041
#_Interleaved=$80000042
#Colors32=$80000043 :#VideoControl=$80000044
#FrontChild=$80000045 :#BackChild=$80000046
#LikeWorkbench=$80000047:#Reserved=$80000048

ShowBitMap [BitMap#]

The  ShowBitMap command is the Amiga-mode version of the Show  command.   It
enables  you  to  change a Screens bitmap allowing double buffered  (flicker
free)  animation to happen on a standard Intuition Screen. Unlike Blitz mode
it  is  better  to  do  ShowBitMap then VWait to sync up  with  the  Amiga's
display,   this  will  make sure the new bitmap is  being  displayed  before
modifying the previous BitMap.

Page 175

R-23: WINDOW COMMANDS

Windows are the heart of the user friendly Amiga operating system.  Not only
are  they the graphics device used for both user input and display  but  are
the  heart  of  the messaging system that communicates this  information  to
your program by way of the events system.

Typically a Blitz program will either open or find a screen to use,   define
a  list of gadgets and then open a window on the screen with the gadget list
attached.  It will then wait for an event such as the user selecting a  menu
or hitting a gadget and act accordingly.

The  program can specify which events they wish to receive by modifying  the
IDCMP  flags  for the window.  Once an event is received Blitz  has  a  wide
range of commands for finding out exactly what the user has gone and done.

Blitz also offers a number of drawing commands that allow the programmer  to
render graphics to the currently used window.

Command Description

Window  Window#,X,   Y,   Width,  Heigh t,  Flags,  Title$,   Dpen,   Spen[,
GadgetList#]

Window opens an Intuition window on the currently used screen.  Window# is a
unique  object number for the new window.  X and Y refer to the offset  from
the top left of the screen the window is to appear at.  Width and Height are
the size of the window in pixels.

Flags  are  the  special window flags that a window can  have  when  opened.
These  flags allow for the inclusion of a sizing gadget,  dragbar  and  many
other  things.  The flags are listed as followed,  with their  corresponding
values.  To select more than one of these flags, they must be logically Or'd
together using the'l ' operator.

For example, to open a window with dragbar and sizing gadget which is active
once opened, you would specify a Flags parameter of $11 $21 $1000.

Title$ is a BASIC string,  either a constant or a variable, that you want to
be the title of the window.

Dpen is the colour of the detail pen of the window.  This colour is used for
the window title.

BPen  is the block pen of the window.  This pen is used for things like  the
border around the edge of the window.

The  optional GadgetList# is the number of a gadgetlist object you have  may
want attached to the window.

After the window has opened, it will become the currently used window.

The  Window  library  has  been  extended to handle  super  bitmap  windows.
SuperBitMap  windows  allow the window to have it's  own  bitmap  which  can
actually  be larger than the window.  The two main benefits of this  feature
are  the window's ability to refresh itself and the ability to scroll around
a large area "inside" the bitmap.

To  attach a BitMap to a Window set the SuperBitMap flag in the flags  field
and include the BitMap# to be attached.

Page 176



Window Flag    Value        Description

WINDOWSIZING    $0001    Attaches sizing gadget to bottom right corner
            of window and allows it to be sized.
WINDOWDRAG    $0002    Allows window to be dragged with the
            mouse by it's title bar.
WINDOWDEPTH    $0004    Lets windows be pushed behind or pulled in
            front of other windows.
WINDOWCLOSE    $0008    Attaches a closegadget to the upper left
            corner of the window.
SIZEBRIGHT    $0010    With GIMMEZEROZERO and
            WINDOWSIZING set, this will leave the
            right hand margin, the width of the sizing
            gadget, clear, and any drawing to the
            window will not extend over this right
            margm.
SIZEBBOTTOM    $0020    Same as SIZEBRIGHT except it leaves a
            margin at the bottom of the window, the
            width of the sizing gadget.
BACKDROP    $0100    This opens the window behind any other
            window that is already opened. It cannot
            have the WINDOWDEPTH flag set also, as
            the window is intended to stay behind all
            others.
GIMME00        $0400    This flag keeps the windows border separate
            from the rest of the windows area. Any
            drawing on the window, extending to the
            borders, will not overwrite the border.
            NOTE: Although convevient, this does take
            up more memory than usual.
BORDERLESS    $0800    Opens a window without any border on it at
            all.
ACTIVATE    $1000    Activates the window once opened.


Use Window Window#

Use  Window  will cause the specified window object to become the  currently
used  window.   Use  Window also automatically performs  a  WindowInput  and
WindowOutput on the specified window.

Free Window Window#

Free Window closes down a window.  This window is now gone,  and can not  be
accessed any more by any statements or functions.  Once a window is  closed,
you  may want to direct the input and output somewhere new,  by calling  Use
Window  on  another window,  DefaultOutput/DefaultInput,  or by  some  other
appropriate means. Window# is the window object number to close.

Page 177

Windowinput Window#

Windowinput will cause any future executions of the Inkey$,  Edit$  or  Edit
functions  to  receive their input as keystrokes from the  specified  window
object.

WindowInput  is automatically executed when either a window is  opened,   or
Use Window is executed.

After a window is closed (using Free Window),  remember to tell Blitz to get
it's  input  from  somewhere  else   useful  (for  example,   using  another
WindowInput  command)   before executing  another  Inkey$,   Edit$  or  Edit
function.

WindowOutput Window#

WindowOutput will cause any future executions of either the Print or  NPrint
statements to send their output as text to the specified window object.

WindowOutput is automatically executed when either a window is  opened,   or
Use Window is executed.

After  a  window  is closed (using Free Window),  remember  to  send  output
somewhere  else  useful  (for example,  using another WindowOutput  command)
before executing another Print or NPrint statement.

DefaultlDCMP IDCMP_Flags

DefaultIDCMP  allows you to set the IDCMP flags used  when  opening  further
windows.  You can change the flags as often as you like, causing all of your
windows to have their own set of IDCMP flags if you wish.

A  window's IDCMP flags will affect the types of 'events' reportable by  the
window. Events are reported to a program by means of either the WaitEvent or
Event functions.

To  select  more than one IDCMP Flag when using DefaultIDCMP,   combine  the
separate flags together using the OR operator ('I ').

Any  windows  opened before any DefaultIDCMP command  is  executed  will  be
opened using an IDCMP flags setting of:

$21 $41 $81 $201 $401 $1001 $2001 $4001 $400001 $80000.

This should be sufficient for most programs.

If you do use DefaultIDCMP for some reason,  it is important to remember  to
include  all  flags  necessary  for the functioning  of  the  program.   For
example,  if you open a window which is to have menus attached to  it,   you
MUST set the $100 (menu selected)  IDCMP flag,  or else you will have no way
of telling when a menu has been selected.

Page 178

    IDCMP    FlagEvent
    $2    Reported when a window has it's size changed.
    $4    Reported when a windows contents have been
        corrupted. This may mean a windows contents may
        need to be re-drawn.
    $8    Reported when either mouse button has been hit.
    $10    Reported when the mouse has been moved.
    $20    Reported when a gadget within a window has been
        pushed 'down'.
    $40    Reported when a gadget within a window has been
        'released'.
    $100    Reported when a menu operation within a window has
        occured.
    $200    Reported when the 'close' gadget of a window has
        been selected.
    $400    Reported when a keypress has been detected.
    $8000    Reported when a disk is inserted into a disk drive.
    $10000    Reported when a disk is removed from a disk drive.
    $40000    Reported when a window has been 'activated'.
    $80000    Reported when a window has been 'de-activated'.

AddlDCMP IDCMP_Flags

AddIDCMP  allows you to 'add in' IDCMP flags to the IDCMP flags selected  by
DefaultIDCMP.   Please refer to DefaultIDCMP for a  thorough  discussion  of
IDCMP flags.

SublDCMP IDCMP_Flags

SubIDCMP  allows  you to 'subtract out' IDCMP flags  from  the  IDCMP  flags
selected  by  DefaultIDCMP.  Please refer to  DefaultIDCMP  for  a  thorough
discussion of IDCMP flags.

WaitEvent

WaitEvent  will  halt  program excution until an Intuition  event  has  been
received.  This event must be one that satisfies the IDCMP flags of any open
windows.  If used as a function,  WaitEvent returns the IDCMP  flag  of  the
event (please refer to DefaultIDCMP for a table of possible IDCMP flags). If
used as a statement, you have no way of telling what event occured.

You  may  find  the  window object number that caused the  event  using  the
EventWindow function.

In  the  case of events concerning gadgets or menus,  further functions  are
available to detect which gadget or menu was played with.

In  the  case of mouse button events,  the MButtons function may be used  to
discover exactly which mouse button has been hit.

IMPORTANT NOTE:  If you are assigning the result of WaitEvent to a variable,
MAKE SURE that the variable is a long type variable.

Page 179



For example: MyEvent.l=WaitEvent

Event

Event works similarly to WaitEvent in that it returns the IDCMP flag of  any
outstanding windows events.  However,  Event will NOT cause program flow  to
halt. Instead, if no event has occured, Event will return 0.

EventWindow

EventWindow may be used to determine in which window the most recent  window
event occured.  Window events are detected by use of either the WaitEvent or
Event commands.

EventWindow  returns  the window object number  in  which  the  most  recent
window event occured

Flush Events [IDCMP_Flag]

When window events occur in Blitz,  they are automatically 'queued' for you.
This means that if your program is tied up processing one window event while
others are being created,  you wont miss out on anything.  Any events  which
may have occured between executions of WaitEvent or Event will be stored  in
a  queue for later use.  However,  there may be situations where you want to
ignore this backlog of events. This is what FlushEvents is for.

Executing  FlushEvents  with  no parameters will  completely  clear  Blitz's
internal event queue,  leaving you with no outstanding events.  Supplying an
IDCMP_Flag parameter will only clear events of the specified type  from  the
event queue.

GadgetHit

GadgetHit  returns the identification number of the gadget that  caused  the
most recent 'gadget pushed' or 'gadget released' event.

As  gadgets in different windows may possibly posess the same identification
numbers,  you may also need to use EventWindow to tell exactly which  gadget
was hit.

MenuHit

MenuHit returns the identification number of the menu that caused  the  last
menu  event.   As with gadgets,  you can have different menus for  different
windows with the same identification number.  Therefore you may also need to
use EventWindow to find which window caused the event.  If no menus have yet
been selected, Menuhit will return - l.

ItemHit

ItemHit  returns the identification number of the menu item that caused  the
last menu event.

SubHit

SubHit returns the identification number of the the menu subitem that caused
the last menu event. If no subitem was selected, SubHit will return -l.

Page 180

MButtons

MButtons returns the codes for the mouse buttons that caused the most recent
'mouse buttons' event.  If menus have been turned off using Menus Off,  then
the  right  mouse button will also register an event and can  be  read  with
MButtons.

RawKey

RawKey  returns the raw key code of a key that caused the most  recent  'key
press' evens.

Qualifier

Qualifier  will  return  the qualifier of the last  key  that  caused  a'key
press'  event  to occur.  A qualifier is a key which alters the  meaning  of
other  keys;   for example the 'shift' keys.  Here is a table  of  qualifier
values and their equivalent keys:

Key            Left.            Right

UnQualified        $8000            $8000
Shift            $8001            $8002
Caps Lock Down        $8004            $8004
Control            $8008            $8008
Alternate        $8010            $8020
Amiga            $8040            $8080

A  combination of values may occur,  if more that one qualifier key is being
held  down.  The way to filter out the qualifiers that you want is by  using
the logical AND operator.

WPlot X, Y,Colour

WPlot plots a pixel in the currently used window at the coordinates  X,Y  in
the colour specified by Colour.

WBox X1, Y1,X2, Y2,Colour

WBox  draws a solid rectangle in the currently used window.  The upper  left
hand coordinates of the box are specified with the Xl and Yl values, and the
bottom right hand corner of the box is specified by the values X2 and Y2.

WCircle X,Y,Radius,Colour

WCircle  allows  you  to draw a circle in the currently  used  window.   You
specify the centre of the circle with the coordinates X,Y.  The Radius value
specifies the radius of the circle you want to draw.  The last value, Colour
specifies what colour the circle will be drawn in.

Page 181

WEllipse X, Y,X Radius, Y Radius,Colour

WEllipse  draws  an ellipse in the currently used window.  You  specify  the
centre  of  the  ellipse with the coordinates X,Y.  X Radius  specifies  the
horizontal radius of the ellipse, Y Radius the vertical radius.

Colour refers to the colour in which to draw the ellipse.

WLine X1, Y1,X2, Y2[,Xn, Yn..],Colour

Wline allows you to draw a line or a series of lines into the currently used
window. The first two sets of coordinates Xl,Yl,X2,Y2, specify the start and
end  points  of  the  initial line.  Any coordinates specified  after  these
initial two,  will be the end points of another line going from the last set
of end points,  to this set. Colour is the colour of the line(s) that are to
be drawn.

WCls [Colour]

WCls  will  clear the currently used window to colour O,   or  a  colour  is
specified,   then it will be cleared to this colour.  If the current  window
was  not  opened with the GIMMEZEROZERO flag set,  then this statement  will
clear  any  border or title bar that the window has.  The InnerCls statement
should be used to avoid these side effects..

InnerCls [Colour]

InnerCls will clear only the inner portion of the currently used window.  It
will  not clear the titlebar or borders as WCls would do if your window  was
not opened with the GIMMEZEROZERO flag set.  If a colour is specified,  then
that colour will be used to clear the window.

WScroll X1, Y1,X2, Y2,Delta X,Delta Y

WScroll  will cause a rectangular area of the currently used  window  to  be
moved  or  'scrolled'.   Xl and.YI specify the  top  left  location  of  the
rectangle,  X2 and Y2 the bottom right.  The Delta parameters determine  how
far  to  move  the  area.  Positive values move the area right/down,   while
negative values move the area left/up.

Cursor Thickness

Cursor  will  set the style of cursor that appears when editing  strings  or
numbers with the Edit$ or Edit functions.  If Thickness is less than 0, then
a  block cursor will be used.  If the Thickness is greater then 0,  then  an
underline Thickness pixels high will be used.

Editat

After  executing an Edit$ or Edit function,  Editat may be used to determine
the  horizontal  character position of the cursor at the time  the  function
was exited.

Through the use of Editat,  EditExit, EditFrom and Edit$, simple full screen
editors may be put together.

Page 182

EditFrom [Characterpos]

EditFrom allows you to control how the Edit$ and Edit functions operate when
used within windows.

If  a  Characterpos  parameter is specified,  then the  next  time  an  edit
function  is  executed,   editing will commence at the  specified  character
position (0 being the first character position).

Also, editing may be terminated not just by the use of the 'return' key, but
also by any non printable character (for example,  'up arrow' or 'Esc') or a
window event. When used in conjunction with Editat and EditExit, this allows
you to put together simple full screen editors.

If Characterpos is omitted, Edit$ and Edit return to normal - editing always
beginning at character postition 0, and 'return' being the only way to exit.
EditExit

EditExit returns the ASCII value of the character that was used  to  exit  a
window  based Edit$ or Edit function.  You can only exit the edit  functions
with  keypresses other than 'return' if EditFrom has been executed prior  to
the edit call.

WindowFont IntuiFont#

WindowFont sets the font for the currently used window. Any further printing
to  this  window  will  be  in the specified font.  IntuiFont#  specifies  a
previously initialized intuifont object created using LoadFont.

WColour Foreground Colour[,Background Colour]

WColour  sets the foreground and background colour of printed text  for  the
currently used window.  Any further text printed on this window will  be  in
these colours.

WJam Jammode

WJam sets the text drawing mode of the currently used window.  These drawing
modes  allow you to do inverted,  complemented and other types of  graphics.
The drawing modes can be OR'ed together to create a combination of them.

Jaml=0

This draws only the foreground colour and leaves the background transparent.
Eg For the letter O, any empty space (inside and outside the letter) will be
transparent.

Jam2=1

This  draws both the foreground and background to the window.  Eg  With  the
letter  O  again,   the  O will be drawn,  but any clear  area  (inside  and
outside) will be drawn in the current background colour.

Complement=2

This will exlusive or (XOR) the bits of the graphics. Eg Drawing on the same
Page 183

place with the same graphics will cause the original display to return.

Inversvid =4

This allows the display of inverse video characters.  If used in conjunction
with Jam2,  it behaves like Jam2,  but the foreground and background colours
are exchanged.

Activate Window#

Activate will activate the window specified by Window#.

Menus OnlOff

The  Menus command may be used to turn ALL menus either on or off.   Turning
menus off may be useful if you wish to read the right mouse button.

WPointer Shape#

WPointer  allows  you to determine the mouse pointer  imagery  used  in  the
currently  used  window.  Shape# specifies an initialized shape  object  the
pointer  is to take it's appearance from,  and must be of 2 bitplanes  depth
(4 colours).

WMove X,Y

WMove will move the current window to screen position X,Y.

WSize Width,Height

WSize  will alter the width and height of the current window to  the  values
specified by Width and Height.

WMouseX

WMouseX  returns the horizontal x coordinate of the mouse  relative  to  the
left  edge of the current window.  If the current window was opened  without
the GIMMEZEROZERO flag set,  then the left edge is taken as the left edge of
the border around the window,  otherwise, if GIMMEZEROZERO was set, then the
left edge is the taken from inside the window border.

WMouseY

WMouseY returns the vertical y coordinate of the mouse relative to  the  top
of  the  current  window.   If the current window  was  opened  without  the
GIMMEZEROZERO  flag set,  then the top is taken as the  top  of  the  border
around the window,  otherwise,  if GIMMEZEROZERO was set,  then the  top  is
taken trom inside the window border.

EMouseX

EMouseX will return the horizontal position of the mouse pointer at the time
the most recent window event occured.  Window events are detected using  the
WaitEvent or Event commands.

Page 184

EMouseY

EMouseY will return the vertical position of the mouse pointer at  the  time
the most recent window event occured.  Window events are detected using  the
WaitEvent or Event commands.

WCursX

WCursX  returns the horizontal location of the text cursor of the  currently
used window. The text cursor position may be set using WLocate.

WCursY

WCursY  returns  the vertical location of the text cursor of  the  currently
used window. The text cursor position may be set using WLocate.

WLocate X, Y

WLocate  is  used to set the text cursor position within the currently  used
window.  X and Y are both specified in pixels as offsets from the  top  left
of  the  window.  Each window has it's own text cursor position,   therefore
changing  the text cursor position of one window will not affect  any  other
window's text cursor position.

WindowX

WindowX returns the horizontal pixel location of the top left corner of  the
currently used window, relative to the screen the window appears in.

WindowY

WindowY  returns the vertical pixel location of the top left corner  of  the
currently used window, relative to the screen the window appears in.

WindowWidth

WindowWidth returns the pixel width of the currently used window.

WindowHeight

WindowHeight returns the pixel height of the currently used window.

InnerWidth

InnerWidth  returns the pixel width of the area inside  the  border  of  the
currently used window.

InnerHeight

InnerHeight returns the pixel height of the area inside the  border  of  the
currently used window.

Page 185

WTopOff

WTopOff  returns the number of pixels between the top of the current  window
border and the inside of the window.

WLeftOff

WLeftOff  returns the number of pixels between the left edge of the  current
window border and the inside of the window.

SizeLimits Min Width,Min Height,Max Width,Max Height

SizeLimits  sets the limits that any new windows can be sized  to  with  the
sizing  gadget.   After calling this statement,  any new windows  will  have
these limits imposed on them.

RastPort (Window#)

RastPort returns the specified Window's RastPort address.  Many commands  in
the graphics.library and the like require a RastPort as a parameter.

PositionSuperBitMap x,y

PositionSuperBitMap is used to display a certain area of  the  bitmap  in  a
super bitmap window.

GetSuperBitMap

After  rendering  changes to a superbitmap window the  bitmap  attached  can
also  be  updated  with the GetSuperBitMap.  After rendering  changes  to  a
bitmap  the  superbitmap  window can be refreshed  with  the  PutSuperBitMap
command. Both commands work with the currently used window.

PutSuperBitMap

See GetSuperBitmap description.

WTitle windowtitle$,screentitle$

WTitle  is  used  to  alter both the current window's  title  bar  and  it's
screens  title bar.  Useful for displaying important stats such  as  program
status etc.

CloseWindow Window#

CloseWindow  has  been added for convenience.  Same as  Free  Window  but  a
little  more  intuitive  (added for those that have  complained  about  such
matters).

WPrintScroll

WPrintScroll will scroll the current window upwards if the  text  cursor  is
below the bottom of the window and adjust the cursor accordingly.  Presently
WPrintScroll  only  works with windows opened  with  the  gimmeO0  flag  set
(#gimmezerozero=$400).

Page 186

WBlit Shape#,x,y

WBlit can be used to blit any shape to the current window. Completely system
friendly  this  command will completely clip the shape  to  fit  inside  the
visible part of the window Use GimmeZeroZero windows for clean clipping when
the window has title/sizing gadgets.

BitMaptoWindow Bitmap#,Window#tsrox,srcy,destx,desty,wid,height]

BitMaptoWindow  will  copy  a  bitmap to a window  in  an  operating  system
friendly manner (what do you expect).  The main use of such a command is for
programs  which  use  the  raw bitmap commands  such  as  the  2D  and  Blit
libraries  for rendering bitmaps quickly but require a windowing environment
for the user inyerface.

EventCode

EventQualifier

EventCode  returns  the  actual code of the  last  Event  received  by  your
program,  EventQualifier returns the contents of the Qualifier field. Of use
with  the  new  GadTools  library and some other low  level  event  handling
requirements.

EventCode  returns  the  actual code of the  last  Event  received  by  your
program,  EventQualifier returns the contents of the Qualifier field. Of use
with  the  new  GadTools  library and some other low  level  event  handling
requirements.

WindowTags Window#,Flags, Title$,[&TagList]l [[Tag,Data]...]

Similar to ScreenTags,  WindowTags allows the advanced user to open a  Blitz
window  with  a  list of OS Tags as described in the documentation  for  the
operating system prior to 2.0.

LoadFont IntuiFont#,Fontname.font$, Y Size [,style]

LoadFont is used to load a font from the fonts: directory. Unlike BlitzFonts
any  size IntuiFont can be used.  The command WindowFont is used to set text
output to a certain IntuiFont in a particular Window.

The  LoadFont  command has been extended with an optional  style  parameter.
The following constants may be combined:

#underl ined= I

#bold=2 #italic=4 #extended=8 ;wider than normal #colour=64 ;hmm use  colour
version I suppose

Page 187

R-24: GADGET COMMANDS

Blitz  provides  extensive support for the creation  and  use  of  Intuition
gadgets.   This  is  done  through  the use  of  GadgetList  objects.   Each
gadgetlist  may contain one or more of the many types of available  gadgets,
and  may be attached to a window when that window is opened using the Window
command.

The  following  is  a table of the gadget flags and the gadget  types  which
they are relevant to:

Bit#     Meaning                 Text     String     Prop     Shape

0    Toggle On/Off                yes        no        no        yes
I    Relative to Right Side of Window     yes        yes        yes        yes
2    Relative to Bottom of Window         yes        yes        yes        yes
3    Size Relative to Width of Window     no        no        yes        no
4    Size Relative to Height of Window     no        no        yes        no
0    Box Select                 yes        yes        yes        yes
6    Prop Gadget has Horizontal Movement     no        no        yes        no
7    Prop Gadget Has Vertical Movement     no        no        yes        no
8    No Border around Prop Gadget         no        no        yes        no
9    Mutually Exclusive             yes        yes        no        no
10    Attach to Window's Right Border     yes        yes        yes        yes
11    Attach to Window's Left Border         yes        yes        yes        yes
12    Attach to Window's Top Border         yes        yes        yes        yes
13    Attach to Window's Bottom Border     yes        yes        yes        yes
14    Use GimmeZeroZero Border        yes        yes        yes        yes

Note:

If Relative Right is set the gadgets X should be negative,  as should it's Y
if  Relative to Bottom is set.  When relative Width or Height flags are  set
negative  Width  and/or Height parameters should be specified  as  Intuition
calculates  actual witdh as WindowWidth+GadgetWidth as it does  height  when
relative size flags are set.

Mutually exclusive radio button type gadgets DO NOT require WorkBench 2.0 to
operate, see ButtonGroup for more information.

The  attach  flags  are  for attaching the gadget  to  one  of  the  windows
borders,   the  GZZGADGET flag is for attaching the gadget  to  the  "outer"
rastport/ layer of a gimme zero zero window.

Here is an example of setting up some radio button style text gadgets:

TextGadget     0,16,16,512,1,"0PTION     l":Toggle     0,1,0n     TextGadget
0,16,32,512,2,"OPTION 2" TextGadget 0,16,48,512,3,"0PTION 3"

Text  Gadgets  may now be used to create 'cycling' gadgets.   Again,   these
gadgets DO

Page 188

NOT require kickstart 2.0 to work.

If  you  create  a  text gadget which contains the 'l  '  character  in  the
gadget's text,  Blitz will recognize this as a 'cycling' gadget,  using  the
'l ' character to separate the options - like this:

TextGadget 0, l 6, l 6,0, l ," HELLO l GOODBYEI SEEYA l "

Now,   each  time this gadget is clicked on,  the gadgets  text  will  cycle
through 'HELLO',  'GOODBYE' and 'SEEYA'. Note that each option is spaced out
to  be  of  equal length.  This feature should not be used with a  GadgetJam
mode of 0.

TextGadget GadgetList#,X, Y, F/ags, /d, Text$

The TextGadget command adds a text gadget to a gadgetlist.  A text gadget is
the  simplest  type  of  gadget  consisting  of  a  sequence  of  characters
optionally surrounded by a border.

Flags should be selected from the table at the start of the chapter.

Boolean gadgets are the simplest type of gadget available.  Boolean  gadgets
are 'off' until the program user clicks on them with the mouse,  which turns
them 'on'.  When the mouse button is released,  these gadgets revert back to
their 'off' state.  Boolean gadgets are most often used for 'Ok' or 'CANCEL'
type gadgets.

Toggle  gadgets  differ in that each time they are clicked  on  they  change
their  state  between 'on' and 'off'.  For example,  clicking  on  a  toggle
gadget  which  is 'on' will cause the gadget to be turned  'off,   and  vice
versa.

X and Y specify where in the window the gadget is to appear.  Depending upon
the Flags setting, gadgets may be positioned relative to any of the 4 window
edges.   If  a gadget is to be positioned relative to either  the  right  or
bottom  edge  of  a  window,  the appropriate X or  Y  parameter  should  be
negative.

Id is an identification value to be attached to this gadget.  All gadgets in
a  gadgetlist should have unique Id numbers,  allowing you to  detect  which
gadget has been selected. Id may be any positive, non-zero number.

Text$ is the actual text you want the gadget to contain.

ButtonGroup Group -

ButtonGroup  allows you to determine which 'group' a number of  button  type
gadgets  belong  to.   Following the execution of ButtonGroup,   any  button
gadgets created will be identified as belonging to the spiecified group. The
upshot  of  all this is that button gadgets are only mutually  exclusive  to
other button gadgets within the same group.

'Group' must be a positive number greater than 0. Any button gadgets created
before a'ButtonGroup' command is executed will belong to group l.

SetGadgetStatus GadgetList#,/d,Va/ue

SetGadgetStatus is used to set a cycling text gadget to a particular  value,
once  set  ReDraw should be used to refresh the gadget to reflect  it's  new
value.

Page 189

GadgetPens Foreground Colour[,Background Colour]

GadgetPens  determines the text colours used when text gadgets  are  created
using  the  TextGadget command.  The default values used for gadget  colours
are a foreground colour of I, and a background colour of 0.

GadgetJam Jammode

GadgetJam  allows  you  to  determine the text rendering  method  used  when
gadgets are created using the TextGadget command.  Please refer to the  WJam
command  in  the  windows  chapter for  a  full  description  of  jam  modes
available.

SelectMode mode

SelectMode  is  used to predefine how gadget rendering will  show  a  gadget
.selection,  modes are I for box and O for inverse. Use prior to creation of
gadgets.

ShapeGadget GadgetList#,X,Y,Flags,ld,Shape#LShape;#]

The  ShapeGadget command allows you to create gadgets with graphic  imagery.
The  Shape#  parameter refers to a shape object containing the graphics  you
wish the gadget to contain.

The  ShapeGadget command has been extended to allow an alternative image  to
be displayed when the gadget is selected.

All other parameters are identical to those in TextGadget.

StringGadget GadgetList#,X, Y,Flags,ld,Maxlen, Width

StringGadget  allows you to create an Intuition style 'text  entry'  gadget.
When clicked on,  a string gadget brings up a text cursor,  and is ready  to
accept text entry trom the keyboard.

X  and Y specifies the gadgets,  position,  relative to the top left of  the
window  it  is  to  appear in.  See the beginning of  the  chapter  for  the
relevant Flags tor a string gadget.

Id is an identification value to be attached to this gadget.  All gadgets in
a  gadgetlist should have unique Id numbers,  allowing you to  detect  which
gadgets has been selected. Id may be any positive, non-zero number.

Maxlen refers to the maximum number of characters which may appear  in  this
gadgets.

Width refers to how wide,  in pixels,  the gadget should be. A string gadget
may  have a width less than the maximum number of characters it may contain,
as characters will be scrolled through the gadget when necessary.

You  may  read the current contents of a string gadget using the  StringText
function.

StringText$ (GadgetList#,ld)

The Stringtext$ function allows you to determine the current contents  of  a
string  gadget.  StringText$ will return a string of characters representing
the string gadgets contents.

Page 190

ActivateString Window#,ld

ActivateString  may  be used to 'automatically' activate  a  string  gadget.
This  is  identical to the program user having clicked in the string  gadget
themselves,   as  the  string  gadget's cursor  will  appear,   and  further
keystrokes will be sent to the string gadget.

It  is often nice of a program to activate Important string gadgets,  as  it
saves  the  user  the hassle of having to reach t'or the  mouse  before  the
keyboard.

ResetString GadgetList#,ld

ResetString  allows you to 'reset' a string gadget.   This  will  cause  the
string gadget's cursor position to be set to the leftmost position.

ClearString GadgetList#,ld

ClearString may be used to clear, or erase, the text in the specified string
gadget.  The cursor position will also be moved to the leftmost position  in
the string gadget.

If  a  string gadget is cleared while it is displayed in a window,  the text
will  not  be erased from the actual display.  To do this,  ReDraw  must  be
executed.

SetStri ng GadgetList#, ID, String$

SetString may be used to initialize the contents of a string gadget  created
with  the  StringGadget  command.    If   the  string  gadget  specified  by
GadgetList#  and  Id is already displayed,  you will also  need  to  exeucte
ReDraw to display the change.

PropGadget GadgetList#,X, Y,Flags,ld, Width,Height

The  PropGadget  command  is  used   to   create  a  'proportional  gadget'.
Proportional  gadgets present a program user with a 'slider bar',   allowing
them to adjust the slider to achieve a desired effect.  Proportional gadgets
are commonly used for the 'R G B' sliders seen in many paint packages.

Proportional  gadgets  have   2   main   qualities  -  a  'pot'  (short  for
potentiometer) setting, and a'body' setting.

The pot setting refers to the current position of the slider bar,  and is in
the  range O through I.  For example,  a proportional gadget which has  been
moved to 'half way' would have a pot setting of '.5'.

The  body  setting  refers to the size of the units the proportional  gadget
represents,  and is again in the range O through 1.  Again  taking  the  RGB
colour  sliders as an example,  each slider is intended to show a particular
value in the range O through 15 - giving a unit size,  or body setting,   of
1/16 or '.0625'.

Put simply,  the pot setting describes 'where' the slider bar is,  while the
body setting describes 'how big' it is.

Proportional  gadgets may be represented as either horizontal  slider  bars,
vertical slider bars, or a combination of both.

See  the  beginning  of  the chapter for relevant Flags  settings  for  prop
gadgets.

X  and  Y  refer to the gadgets position,  relative to the top left  of  the
window it is opened in.  Width and Height refer to the size of the area  the
slider should be allowed to

Page 191

move in.

Id is a unique, non zero number which allows you to identify when the gadget
is mampulated.

Proportional  gadgets  may  be  altered  using  the  SetVProp  and  SetHProp
commands,  and read using the VPropPot,  VPropBody,  HPropPot and  HPropBody
functions.

SetHProp GadgetList#,ld,Pot,Body

SetHProp  is used to alter the horizontal slider qualities of a proportional
gadget. Both Pot and Body should be in the range O through l.

If  SetHProp  is  executed while the specified gadget is already  displayed,
execution of the ReDraw command will be necessary to display the changes.

For  a  full  discussion  on  proportional gadgets,   please  refer  to  the
PropGadget command.

SetVProp GadgetList#,ld,Pot, Body

SetVProp  is  used to alter the vertical slider qualities of a  proportional
gadget. Both Pot and Body should be in the range O through l.

If  SetVProp  is  executed while the specified gadget is already  displayed,
execution of the ReDraw command will be necessary to display the changes.

HPropPot (GadgetList#,ld)

The HPropPot function allows you to determine the current 'pot' setting of a
proportional gadget.  HPropPot will return a number from O up to,   but  not
including, l, reflecting the gadgets current horizontal pot setting.

HPropBody (GadgetList#,ld)

The HPropBody function allows you to determine the current 'body' setting of
a proportional gadget.  HPropBody will return a number from O up to, but not
including, l, reflecting the gadgets current horizontal body setting.

VPropPot (GadgetList#,ld)

The VPropPot function allows you to determine the current 'pot' setting of a
proportional gadget.

VPropPot will return a number from O up to, but not including, l, reflecting
the gadgets current vertical pot setting.

VPropBody (GadgetList#,ld)

The VPropBody function allows you to determine the current 'body' setting of
a proportional gadget.

VPropBody  will  return  a  number from O up to,   but  not  including,   l,
reflecting the gadgets current vertical body setting.

Redraw Window#,id

ReDraw  will  redisplay the specified gadget in the specified window.   This
command  is mainly of use when a proportional gadget has been altered  using
SetHProp or SetVProp and needs to be redrawn, or when a string gadget has

Page 192

been cleared using ClearString, and, likewise, needs to be redrawn.

Borders [Onl Off]l [Width, Height]

Borders serves 2 purposes.  First, Borders may be used to turn on or off the
automatic  creation of borders around text and string gadgets.  Borders  are
created  when  either a Textgadget or StringGadget command is executed.   If
you  wish  to  disable  this,  Borders Off should  be  executed  before  the
appropriate TextGadget or StringGadget command.

Borders  may also be used to specify the spacing between a gadget  and  it's
border,   Width  referring to the left/right spacing,   and  Height  to  the
above/below spacing.

BorderPens Highlight Colour,Shadow Colour

BorderPens  allows you to control the colours used when gadget  borders  are
created.  Gadget borders may be created by the TextGadget,  StringGadget and
GadgetBorder commands.

HighLight  Colour  refers to the colour of the top and  left  edges  of  the
border, while Shadow Colour refers to the right and bottom edges.

The  default value for HighLight Colour is l.  The default value for  Shadow
Colour is 2.

Gadget Bo rde r X, Y, Width, Heigh t

The  GadgetBorder command may be used to draw a rectangular border into  the
currently used window.

Proportional  gadgets  and shape gadgets do not have  borders  automatically
created  tor them.  The GadgetBorder command may be used,  once a window  is
opened, to render borders around these gadgets.

X,Y,   Width  and  Height refer to the position of the gadget  a  border  is
required around.  GadgetBorder will automatically insert sapces between  the
gadget and the border.  The Borders command may be used to alter the  amount
of spacing.  Of course, GadgetBorder may be used to draw a border around any
arbitary area, regardless of whether or not that area contains a gadget.

GadgetStatus (GadgetList#,ld)

GadgetStatus may be used to determine the status of the specified gadget. In
the case of toggle' type gadget,  GadgetStatus will return true (-l)  if the
gadget is currently on, or false (O) if the gadget is currently off.

In the case of a cycling text gadget,  GadgetStatus will return a value of l
or greater representing the currently displayed text within the gadget.

Buttonid (GadgetList#,ButtonGroup)

ButtonId  may  be used to determine which gadget within a  group  of  button
type gadgets is currently selected.  The value returned will be the GadgetId
of the button gadget currently selected.

Page 193

Enable GadgetList#,ld

A gadget when disabled is covered by a "mesh" and can not be accessed by the
user.   The commands Enable and Disable allow the programmer to access  this
feature of Intuition.

Disable GadgetList#,ld

A gadget when disabled is covered by a "mesh" and can not be accessed by the
user.   The commands Enable and Disable allow the programmer to access  this
feature of Intuition.

Toggle GadgetList#,ld [,On| Off]

The  Toggle  command  in the gadget library has been  extended  so  it  will
actually toggle a gadgets status if the On| Off parameter is missing.

Page 194

R-25: MENU COMMANDS

Blitz supports many commands for the creation and use of Intuition menus.

Menus  are  created  through  the use of MenuList  objects.   Each  menulist
contains  an  entire set of menu titles,  menu items and possibly  sub  menu
items.

Menulists are attached to windows through the SetMenu command.

Each  window  may use a separate menulist,  allowing you to attach  relevant
menus to different windows.

MenuTitle Menulist#,Menu,Title$

MenuTitle is used to add a menu title to a menulist. Menu titles appear when
the right mouse button is held down,  and usually have menuitems attached to
them.

Menu  specifies  which menu the title should be used for.   Higher  numbered
menus  appear  further to the right along the menu bar,  with  O  being  the
leftmost menu.  Menutitles should be added in left to right order, with menu
O being the first created, then I and so on...

Title$ is the actual text you want to appear when the right mouse button  is
pressed.

Menultem MenuList#, Flags, Menu,ltem,ltemtext$[, Shortcut$]

Menultem  is used to create a text menu item.  Menu items appear  vertically
below  menu titles when the mouse is moved over a menu title with the  right
mouse button held down.

Flags affects the operation of the menu item.  A value of O creates a  stand
'seleect' menu item.

A  value of I creates a 'toggle' menu item.  Toggle menu items are used  for
'on/off' type options.  When a toggle menu item is selected,  it will change
state between on and off.  An 'on' toggle item is identified by a 'tick'  or
check mark.

A  value  of  2 creates a special type of toggle menu item.  Any menu  items
which  appear under the same menu with a Flags setting of 2 are said  to  be
mutually exclusive.  This means that only I of them may begin the 'on' state
at  one time.  If a menu item of this nature is toggled into the 'on' state,
any  other mutually exclusive menu items which may have previously been 'on'
will be automatically turned 'off'.

Flags  values of 3 and 4 correspond to values I and 2,  only the  item  will
initially appear in the 'on' state.

Menu specifies the menu title under which the menu item should appear.

Item specifies the menu item number this menu item should be referenced  as.
Higher numbered items appear further down a menu item list, with O being the
topmost  item.  Menu items should be added in 'top down' order,   with  menu
item O being the first item created.

Itemtext$ is the actual text for the menu item.

An optional Shortcut$ string allows you to select a one character 'keyboard

Page 195

shortcut' for the menu item.

Shapeltem MenuList#, Flags,Menu, Item, Shape#

ShapeItem is used to create a graphical menu item.

Shape#  refers to a previously initialized shape object to be  used  as  the
menu  item's  graphics.  All other parameters are  identical  to  those  for
MenuItem.

Subitem Men uList#, Flags, Menu, ltem, Subitem, Subitem text$t Shortcut$]

All menu items may have an optional list of sub menu items attached to them.
To attach a sub menu item to a menu item, you use the SubItem command.

Item specifies the menu item to attach the sub item to.

Subitem refers to the number of the sub menu item to attach. Higher numbered
sub items appear further down a sub item list,  with 0 being the topmost sub
item.  Sub items should be added in 'top down' order,  with sub item 0 being
created first.

.   Subitemtext$ specifies the actual text for the sub item.  As  with  menu
items,   sub  items  may  have  an  optional  keyboard  shortcut  character,
specified using the Shortcut$ parameter.

All other parameters are identical to the MenuItem command.

ShapeSub MenuList#,Flags,Menu,ltem,Subitem,Shape#

ShapeSub  allows you to create a graphic sub menu item.  Shape# specifies  a
previously created shape object to be used as the sub item's graphics.

All other parameters are identical to those in SubItem.

SetMenu MenuList#

SetMenu  is  used to attach a menulist to the currently used  window.   Each
window may have only one menulist attached to it.

MenuGap X Gap, Y Gap

Executing  MenuGap  before creating any menu titles,  items  or  sub  items,
allows you to control the layout of the menu.

X Gap refers to an amount,  specified in pixles,  to be inserted to the left
and  right of all menu items and sub menu items.  Y Gap refers to an amount,
again in pixels,  to be inserted above and below all menu items and sub menu
items.

SubitemOff X Offset, Y Offset

SubItemOff allows you to control the relative position of the top of a  list
of sub menu items, in relation to their associated menu item.

Whenver a menu item is created which is to have sub menu items,  it's a good
idea to append the name of the menu item with the '>>' character.  This  may
be  done using Chr$(187).  This gives the user a visual indication that more
options are available. To position the sub menu items correctly so that they
appear after the '>>' character, SubItemOff should be used.

Page 196


MenuState MenuList#t Menu[, Item[, Subitem]]], Onl Off

The MenuState command allows you to turn menus, or sections of menus, on
or off.

MenuState with just the MenuList# parameter may be used to turn an entire
menu list on or off.

MenuState with MenuList# and Menu parameters may be used to turn a menu
on or off.

Similarly,   menu items and sub items may be turned on or off by  specifying
the appropriate parameters.

MenuColour Colour

MenuColour  allows you to determine what colour any menu item  or  sub  item
text  is  rendered in.  MenuColour should be executed before the  approprate
menu item commands.

Men uChecked (MenuList#, Menu,ltem[, Subitemp

The  MenuChecked function allows you to tell whether or not a 'toggle'  type
menu item or menu sub item is currently 'checked' or ton'.  If the specified
menu item or sub item is in fact checked,  MenuChecked will return 'true' (-
l). If not, MenuChecked will return 'false' (O).

Page 197

R-26: GADTOOLS COMMANDS

GadTools  are a new system of Gadgets added to the Amiga's operating  system
in   version 2.0.  They are Improved in both looks and performance over the
older standard Gadgets.

In  order for certain GadTools gadgets to tunction correctly the first thing
to make sure is that the Window has the correct IDCMP flags set:

#MOUSEMOVE=$10 ;needed when user drags a slider #INTUITICKS=$400000  ;needed
when user holds down an arrow AddIDCMP#MOWSEMOVE+#INTUITICKS

To add GadTools Gadgets to the window simply create a list from the commands
listed below and use the AttachGTList command to add them to the window.

For most GTGadgets your program should only act on a #GadgetUp message.  The
GadgetHit  function will return the ID of the gadget the user has  just  hit
and the EventCode function will contain it's new value.

Use  GTGetString  and GTGetInteger functions to read  the  contents  of  the
GadTools string gadgets after a #GadgetUp message.

    GTadgetFlag        Value
    #_LEFT    =    I    ;position of text label
    #_RIGHT    =    2
    #_ABOVE    =    4
    #_BELOW    =    8
    #_IN    =    $10
    #_Highlight    =    $20    ;gadget is highlighted initially
    #_Disable    =    ,$40    ;gadget is disabled initially
    #_Immediate    =    $X0    ;report GadgetDown flag
    # BoolValue    =    $100    ;gadget is on initially

    #_Scaled    =    $200 ;scale arrowsize on scroller gadget
    # Vertical    =    $400 ;make GTPropGadget vertical

GTButton GTList#, id,x,y, w,h, Text$, flags

Same  as  Blitz's TextGadget but with the added flexibility of  placing  the
label Text$ above, below to the left or right of the button (see flags).

GTCheckBox GTList#,id,x,y, w,h, Text$,flags

A box with a check mark that toggles on and off,  best used for options that
are either enabled or disabled.

GTCycle GTList#,id,x,y, w,h, Text$,flags, Options$

Used for offering the user a range of options,  the options string should be
a list

Page 198

of options separated by the l character ea. "HIRES l LORES l SUPER HIRES "

GTlnteger GTList#,id,x,y, w,h, Text$,flags,default

A  string  gadget  that allows only numbers to be entered  by  the  user.See
GTSetInteger and GTGetInteger for information about accessing  the  contents
of a GTInteger gadget.

GTListView GTList#,id,x,y, w,h, Text$,f/ags,/istO

The  ListView gadget enables the user to scroll through a list  of  options.
These  options must be contained in a string field of a Blitz  linked  list.
Currently  this string field must be the second field,  the  first  being  a
word type. *See the GTChangeList command for more details.

GTMX GTList#,id,x,y, w,h, Text$,f/ags, Options$

GTMX  is an exclusive selection gadget,  the Options$ is the same as GTCycle
in  format,  GadTools then displays all the options in a vertical list  each
with a hi-light beside them.

GTNumber GTList#,id,x,y, w, h, Text$, f/ags, va/ue

This  is  a readonly gadget (user cannot interact with it)  used to  display
numbers. See GTSetInteger to update the contents of this read only "display"
gadget.

GTPalette GTList#,id,x,y, w,h, Text$, f/ags, depth

Creates a number of coloured boxes relating to a colour palette,

GTSc roller GTList#,id,x,y, w,h, Text$, f/ags, Visib/e, Tota/

A  prop  type  gadget  tor  the user to control  an  amount  or  level,   is
accompanied by a set of arrow gadgets

GTSlider GTList#,id,x,y, w,h, Text$,f/ags,Min,Max

Same  as  Scroller but for controlling the position of the display inside  a
larger view.

GTString GTList#,id,x,y,w,h,Text$,flags,MaxChars

A  standard  string  type  gadget.   See  GTSetString  and  GTGetString  for
accessing the contents of a GTString gadget.

GTText GTList#,id,x,y, w,h, Text$,f/ags,Disp/ay$

A  read  only  gadget  (see GTNumber)  for displaying  text  messages.   See
GTSetString for updating the contents of this read only "display" gadget.

GTShape  GTList#,   id,x,y,  f/ags,Shape#[,  Shape#] Similar  to  the  Blitz
ShapeGadget allowing IFF graphics that are loaded into

Page 199

Blitz shape objects to be used as gadgets in a window.

AttachGTList GTList#, Window#

The  AttachGTList command is used to attach a set of GadTools gadgets  to  a
Window after it has been opened.

GTTags Tag, Value 1,Tag, Value...]

The  GTTags  command can be used prior to initialisation of any  of  the  12
gadtools gadgets to preset any relevant Tag fields.  The following are  some
useful Tags that can be used with GTTags:

#tag=$80080000
#GTCB Checked=#tag+4        ; State of checkbox
#GTLV_Top=#tag+5        ; Top visible item in listview
#GTLV_ReadOnly=#tag+7        ; Set TRUE if lisiview is ReadOnly
#GTMX_Active=#tag+ 10        ; Active one in mx gadget
#GTTX_Text=#tag+l ]        ; Text to display
#GTNM_Number=#tag+ 13        ; Number to display
#GTCY_Active=#tag+ 15        ; The active one in the cycle gad
#GTPA_Color=#tag+ 17        ; Palette color
#GTPA ColorOffset=#tag+ 18    ; First color to use in palette
#GTSC_Top=#tag+21        ; Top visible in scroller
#GTSC_Total=#tag+22        ; Total in scroller area
#GTSC_Visible=#tag+23        ; Number visible in scroller
#GTSL_Level=#tag+40        ; Slider level
#GTSL_MaxLevelLen=#tag+41    ; Max length of printed level
#GTSL_LevelFormat=#tag+42    ;* Format string for level
#GTSL_LevelPlace=#tag+43    ;* Where level should be placed
#GTLV_Selected=#tag+54        ; Set ordinal number of selected
#GTMX_Spaci ng=#tag+61        ;* Added to font height

All  of  the above except for those marked * can be set after initialisation
of the Gadget using the GTSetAttrs command.

The  following  is  an example of creating a slider gadget  with  a  numeric
display:

f$="%21d    "   GTTags   #GTSLLevelFormat,&f$,#GTSLMaxLevelLen,4    GTSlider
2,10,320,120,200,20,"GTSLIDER",2,0,10

GTGadPtr (GTList#,id)

GTGadPtr  returns  the actual location of the specified GadTools  gadget  in
memory.

GTBevelBox GTList#,x,y,w,h,flags

GTBevelBox  is  the GadTools library equivalent of the Borders  command  and
can be used to render frames and boxes in the currently used Window.

Page 200

GTChangeList GTList#,id [,List() ]

GTChangeList must be used whenever a List attached to a GTListView needs  to
be  modified.  Call GTChangeList without the List()  parameter to  free  the
List, modify it then reattach it with another call to GTChangeList this time
using the List() parameter.

GTSetAttrs GTList#,id [, Tag, Value...]

GTSetAttrs can be used to modify the status of certain GadTools gadgets with
the relevant Tags. See GTTags for more information.

GTSetString GTList#,id,string$

Used  with  both  GTString and GTText gadgets,  GTSetString  will  not  only
update the contents of the gadget but redraw it also.

GTSetinteger GTList#,id,value

Used  with both GTInteger and GTNumber gadgets,  GTSetInteger will not  only
update the contents of the gadget but redraw it also.

GTGetString GTList#,id

Used to read the contents from a GTString gadget.

GTGetinteger GTList#,id

Used to read the contents from a GTlnteger gadget.

GTGetAttrs (GTList#,id, Tag)

A 3.0 specific command. See C= documentation for more information.

GTEnable GTList#,ld

Allows GTGadgets to be enabled and disabled.

GTDisable GTList#,ld

Allows GTGadgets to be enabled and disabled.

GTToggle GTList#,ld[,Onl Off]

GTToggle  allows the programmer to set Boolean gadgets such as GTButton  and
GTCheckbox to a desired state.

GTStatus (GTList#,ld)

GTStatus returns the status of the gadtools toggle gadgets,  a  value  of  ]
means the the gadget is selected, O deselected.

Page 201


R-27: ASL LIBRARY COMMANDS

The  ASL Library features several friendly requesters that programs can  use
on machines equipped with WorkBench 2.0 and above.

ASLFileRequest$ (Title$,Pathname$,Filename$ tPattern$] [,x,y, w,h] )

The  ASL  File  Requester  is  nice.  Except tor  the  highlight  bar  being
invisible on directories you get to use keyboard for everything,  stick in a
pattern$  to  hide certain files and of course you get what  ever  size  you
want.   I  made it call the Blitz file requester if the program  is  running
under 1.3 (isn't that nice!).  There is a fix that patches the ReqTools file
requester but that doesn't have the date field.

I  couldn't  get the Save-Only tag or the "Create Directory" option  working
maybe next upgrade.

ASLPathRequest$ (Title$,Pathname$ [,x,y, w,h] )

Same  as  ASLFileRequest$ except will just prompt the user for a  path  name
(directory) rather than an actual file.

ASLFontRequest (enable flags)

The  ASL  Font Requester is also pretty useful.  The flags parameter enables
the user to modify the following options:

#pen=1 :#bckgrnd=2:#style=4:#drawmode=8:#fixsize=16

It  doesn't seem to handle colour fonts,  no keyboard shortcuts  so  perhaps
patching ReqTools is an option for this one.  The following code illustrates
how  a .fontinfo structure is created by a call to ASLFontRequest (just like
programming in a high level language man!).

ASLScreenRequest (enable flags)

Those  who  are  just  getting to grips with 2.0 and above  will  find  this
command makes your programs look really good,  however I haven't got time to
explain  the  difficulties of developing programs that work  in  all  screen
resolutions (what are ya?).

NEWTYPE .fontinfo
name.s
ysize.w
style.b:flags.b
pen1.b:pen2:drawmode:pad
End NEWTYPE

FindScreen O

*f.fontinfo=ASLFontRequest(15)

If *f
    NPrint *f\name
    NPrint *f\ysize
    NPrint *f\penl
    NPrint *f\pen2
    NPrint 8f\drawmode
Else
    NPrint "cancelled"
Endif

MouseWait

Page 202


R-28: AREXX CONTROL COMMANDS

ARexx allows communication between different Amiga applications allowing for
some extensive and powerful control over applications by the programmer.

CreateMsgPort ("Name")

CreateMsgPort is a general Function and not specific to ARexx.

CreateMsgPort  opens an intuition PUBLIC message port of the  name  supplied
as the only argument. If all is well the address of the port created will be
returned to you as a LONGWORD so the variable that you assign it  to  should
be of type long.

If  you do not supply a name then a private MsgPort will be opened for  you.
Port. I =CreateMsgPort( " PortName" )

It  is important that you check you actually succeeded in opening a port  in
your program. The following code or something similar will suffice.

Port. I=CreateMsgPort( "Name" ) IF Port=0 THEN Error_Routine{ }

The  name  you give your port will be the name that Arexx looks for  as  the
HOST  address,(and is case sensitive)  so take this into consideration  when
you  open  your port.  NOTE IT MUST BE A UNIQUE NAME AND SHOULD NOT  INCLUDE
SPACES.

DeleteMsgPort()  is used to remove the port later but this is  not  entirely
necessary as Blitz will clean up for you on exit if need be.

DeleteMsgPort (Port)

DeleteMsgPort    deletes   a   MessagePort   previously    allocated    with
CreateMsgPort().  The only argument taken by DeleteMsgPort  is  the  address
returned by CreateMsgPort().  If the Port was a public port then it will  be
removed from the public port list.

Port. l=CreateMsgPort( "Name") IF Port=0 Then End DeleteMsgPort Port

Error checking is not critical as if this fails we have SERIOUS PROBLEMS.

YOU  MUST WAIT FOR ALL MESSAGES FROM AREXX TO BE RECEIVED BEFORE YOU  DELETE
THE  MSGPORT.  h YOU NEGLECT TO DELETE A MSGPORT BLITZ2 WILL DO IT  FOR  YOU
AUTOMATICALLY ON PROGRAM EXIT.

CreateRexxMsg (ReplyPort,"exten' "HOST")

CreateRexxMsg()  allocates a special Message structure used  to  communicate
with  Arexx.  If all is successful it returns the LONGWORD address  of  this
rexxmsg structure.

The  arguments  are  ReplyPort  which   is  the  long  address  returned  by
CreateMsgPort().  This is the Port that ARexx will reply  to  after  it  has
finished with the message.

Page 203

EXTEN  which is the exten name used by any ARexx script you are  wishing  to
run.  i.e. if you are attempting to run the ARexx script test.rexx you would
use an EXTEN of "rexx".

HOST is the name string of the HOST port.  Your program is usually the  HOST
and  so  this  equates  to the name you gave your port  in  CreateMsgPort().
REMEMBER IT IS CASE SENSITIVE.

As  we  are  allocating resources error checking is  important  and  can  be
achieved with the following code:

msg.l=CreateRexxMsg(Port, "rexx","HostName" ) IF msg=0 THEN Error_Routine{ }
DeleteRexxMag rexxmsg

DeleteRexxMsg  simply  deletes a RexxMsg Structure previously  allocated  by
CreateRexxMsg().  It takes a single argument which is the long address of  a
RexxMsg structure such as returned by CreateRexxMsg().

msg.l=CreateRexxMsg(Port, "rexx ","HostName") IF msg=0 THEN Error Routine( }
DeleteRexxMsg msg

Again if you neglect to delete the RexxMsg structure Blitz will do this  for
you on exit of the program.

ClearRexxMsg Arexxmsg

ClearRexxMsg is used to delete and clear an ArgString from one  or  more  of
the Argument slots in a RexxMsg Structure.  This is most useful for the more
advanced  programmer  wishing  to   take  advantage  of  the  Arexx  #RXFUNC
abilities.

The  arguments  are a LONGWORD address of a RexxMsg structure.  ClearRexxMsg
will always work from slot number I forward to 16.

FillRexxMsg ( rexxmsg,&FillStruct)

FillRexxMsg  allows  you to fill all 16 ARGSlots if  necessary  with  either
ArgStrings  or numerical values depending on your requirement.   FillRexxMsg
will  only  be used by those programmers wishing to do more advanced  things
with  Arexx,  including adding libraries to the ARexx library list,   adding
Hosts,Value Tokens etc.  It is also needed to access Arexx using the #RXFUNC
flag.  The arguments are a LONG Pointer to a rexxmsg.  The LONG address of a
FillStruct  NEWTYPE structure.  This structure is defined in  the  Arexx.res
and has the following form.

NEWTYPE .FillStruct

    Flags.w    ;Flag block
    ArgsO.1    ; argument block (ARG0-ARG15)
    Argsl.l    ; argument block (ARG0-ARG15)
    Args2.1    ; argument block (ARG0-ARG15)
    Args3.1    ; argument block (ARG0-ARG15)
    Args4.1    ; argument block (ARG0-ARG15)
    Args5.1    ; argument block (ARG0-ARG15)
    Args6.1    , argument block (ARG0-ARG15)
    Args7.1    , argument block (ARG0-ARG15)
    Args8.1    ; argument block (ARG0-ARG15)

Page 204


Args9.1        ; argument block (ARG0-ARG15)
Argsl O.l    ; argument block (ARG0-ARG15)
Argsl 1.1    ; argument block (ARG0-ARG15)
Argsl2.1    ; argument block (ARG0-ARG15)
Argsl3.1    ; argument block (ARG0-ARG15)
Argsl4.1    ; argument block (ARG0-ARG15)
Args 1 5.1    ; argument block (ARG0-ARG15)
EndMark.l    ; End of the FillStruct
End NEWTYPE

The  Args?.l  are  the  16  slots  that can possibly  be  filled  ready  for
converting  into  the  RexxMsg structure.   The  Flags.w  is  a  WORD  value
representing  the  type  of  LONG word you are supplying  for  each  ARGSLOT
(Arg?.l).

Each  bit in the Flags WORD is representative of a single Args?.l,  where  a
set  bit  represents  a  numerical value  to  be  passed  and  a  clear  bit
represents  a  string  argument  to be converted  into  a  ArgString  before
installing in the RexxMsg.  The Flags Value is easiest to supply as a binary
number to make the bits visible and would look like this.

%0000000000000000    ;represents   that   all   Arguments    are    Strings.
%0110000000000000 ;represent second&third as being integers.

FillRexxMsg expects to find the address of any strings in the Args?.l  slots
so  it is important to remember when filling a FillStruct that you must pass
the  string  address  and not the name of the string.  This  is  acomplished
using the '&' address of operand.

So to use FillRexxMsg we must do the following things in our program:

1. Allocate a FillStruct 2. Set the flags in the FillStruct\Flags.w

3.   Fill the FillStruct with either integer values or the addresses of  our
string arguments.

4.   Call  FillRexxMsg with the LONG address of our  rexxmsg  and  the  LONG
address of our FillStruct.

To accomplish this takes the following code:

;Allocate our FillStruct (called F)
DEFTYPE.FillStruct F
;assign some string arguments
T$="open " :T1$="-0123456789"
;Fill in our FillStruct with flags and (&) addresses of our strings
F\Flags= %001 0000000000000,&T$,&T I $,4
;Third argument here is an integer (4).
Port.l=CreateMsgPort( "host")
msg.l=CreateRexxMsg(Port,"vc","host")
FillRexxMsg msg,&F
;<-3 ergs see #RXFUNC
SendRexxCommand msg,"",#RXFUNCI #RXFF RESULTI 3

Page 205


CreateArgString ("this is a string")

CreateArgString()  builds an ARexx compatible ArgString structure around the
provided string.  All strings sent to,  or received from Arexx  are  in  the
form of ArgStrings. See the TYPE RexxARG.

If  all  is  well  the  return  will  be a LONG  address  of  the  ArgString
structure.   The  pointer will actually point to the NULL terminated  String
with the remainder of the structure available at negative offsets.

DeleteArgString ArgString

DeleteArgString is designed to Delete ArgStrings allocated by  either  Blitz
or  ARexx in a system friendly way.  It takes only one argument the LONGWORD
address of an ArgString as returned by CreateArgString().

SendRexxCom mend rexxmsg, "commands/ring ",#RXCOMMI #RXFF RESUL T

SendRexxCommand  is designed to fill and send a RexxMsg structure  to  ARexx
inorder to get ARexx to do something on your behalf.  The arguments  are  as
follows;

rexxmsg:   the  LONGWORD  address  of a RexxMsg  structure  as  returned  by
CreateRexxMsg().

commands/ring:  the command string you wish to send to  ARexx.   This  is  a
string as in "this is a string" and will vary depending on what you wish  to
do  with ARexx.  Normally this will be the name of an ARexx script file  you
wish to execute.  ARexx will then look for the script by the name as well as
the  name with the exten added.(this is the exten you used when you  created
the  RexxMsg structure using CreateRexxMsg()).  This could also be a  string
file. That is a complete ARexx script in a single line.

ActionCodes:  the flag values you use to tell ARexx what you want it  to  do
with the commandstring you have supplied.

COMMAND (ACTION) CODES

The command codes that are currently implemented in the resident process are
described  below.  Commands are listed by their mnemonic  codes,followed  by
the valid modifier flags.  The final code value is always the logical OR  of
the code value and all of the modifier flags selected.  The command code  is
installed in the rm_Action field of the message packet.

RXADDCON:

This  code specifies an entry to be added to the Clip List.  Parameter  slot
ARGO points to the name string,slot ARGI points to the value string,and slot
ARG2 contains the length of the value string.

The  name and value arguments do not need to be argstrings,but can  be  just
pointers  to storage areas.  The name should be a null-terminated string,but
the value can contain arbitrary data including nulls.

Page 206

RXADDFH:

This  action code specifies a function host to be added to the Library List.
Parameter  slot  ARGO points to the (null-terminated)  host name  string,and
slot  ARG  I  holds  the search priority for the node.  The search  priority
should  be an integer between 100 and -100 inclusive;the remaining  priority
ranges  are  reserved for future extensions.  If a node already exists  with
the same name,the packet is returned with a warning level error code.

Note that no test is made at this time as to whether the host port exists.

RXADDLIB:

This code specifies an entry to be added to the Library List. Parameter slot
ARGO  points to a null-terminated name string referring either to a function
library  or  a function host.  Slot ARG I is the priority for the  node  and
should  be an integer between 100 and -100 inclusive;the remaining  priority
ranges  are  reserved for future extensions.  Slot ARG2 contains  the  entry
Point offset and slot ARG3 is the library version number.  If a node already
exists with the same name,the packet is returned with a warning level  error
code.   Otherwise,a  new  entry is added and the  library  or  host  becomes
available to ARexx programs.  Note that no test is made at this time  as  to
whether the library exists and can be opened

RXCOMM [RXFF_TOKEN] [RXFF STRING] [RXFF_RESULT] [RXFF N010]

Specifies  a  command-mode invocation of an ARexx program.   Parameter  slot
ARGO  must  contain an argstring Pointer to the command  string.   The  RXFB
TOKEN  flag specifies that the command line is to be tokenized before  being
passed to the invoked program.  The RXFB_STRING flag bit indicates that  the
command  string  is  a "string file." Command invocations  do  not  normally
return  result strings,but the RXFB_RESULT flag can be set if the caller  is
prepared  to  handle  the cleanup associated with a  returned  string.   The
RXFB_NOIO  modifier  suppresses the inheritance  of  the  host's  input  and
output streams.

RXFUNC [RXFF_RESULT] [RXFF STRING] [RXFF_N010] argcount

This  command  code  specifies a function invoction.   Parameter  slot  ARGO
contains a pointer to the function name string,and slots ARGI through  ARG15
point to the argument strings,all of which must be passed as argstrings. The
lower byte of the command code is the argument count;this count excludes the
function  name  string itself.  Function calls normally set the  RXFB_RESULT
flag,but this is not mandatory.  The RXFB_STRING modifier indicates that the
function  name  string is actually a "string file".  The RXFB_NOIO  modifier
suppresses the inheritance of the host's input and output streams.

RXREMCON:  This code requests that an entry be removed from the  Clip  List.
Parameter  slot ARGO points to the null-terminated name to be removed.   The
Clip  List is searched for a node matching the supplied name,and if a  match
is  tound  the list node is removed and recycled.  If no match is found  the
packet is returned with a warning error code.

RXREMLIB:  This command removes a Library List entry.  Parameter  slot  ARGO
points  to the null terminated string specifying the library to be  removed.
The Library List is searched for a node matching the library name,and  if  a
match  is found the node is removed and released.  If no match is found  the
packet is returned with a warning error code. The libary node will

Page 207

not be removed if the library is currently being used by an ARexx program.

RXTCCLS:

This  code requests that the global tracing console be closed.  The  console
window  will  be  closed immediately unless one or more ARexx  programs  are
waiting for input from the console.  In this event,the window will be closed
as soon as the active programs are no longer using it.

RXTCOPN:

This  command requests that the global tracing console be opened.  Once  the
console  is open,all active ARexx programs will divert their tracing  output
to  the  console.   Tracing  input(for interactive  debugging)will  also  be
diverted  to  the  new  console.  Only one console can be  opened;subsequent
RXTCOPN requests will be returned with a warning error message.

MODIFIER FLAGS

Command  codes  may  include  modifier flags to  select  various  processing
options.   Modifier flags are specific to certain commands,and  are  ignored
otherwise.

RXFF_N010:

This  modifier is used with the RXCOMM and RXFUNC command codes to  suppress
the automatic inheritance of the host's input and output streams.

RXFF NONRET:

Specifies that the message packet is to be recycled by the resident  process
rather  than  being returned to the sender.  This implies  that  the  sender
doesn't  care  about  whether  the   requested  action  succeeded,since  the
returned  packet  provides the only means of acknowledgement.   (RXFF_NONRET
MUST NOT BE USED AT ANY TIME)

RXFF RESULT:

This modifer is valid with the RXCOMM and RXFUNC commands,and requests  that
the  called  program  return  a  result string.   If  the  program  EXITs(or
RETURNs)with an expression,the expression result is returned to  the  caller
as an argstring.  This ArgString then becomes the callers responsibility  to
release.  This is automatically accomplished by using GetResultString().  It
is  therefore  imperitive  that if you use RXFF_RESULT  then  you  must  use
GetResultString()  when the message packet is returned to you  or  you  will
incure a memory loss equal to the size of the ArgString Structure.

RXFF_STRING:

This  modifer  is  valid  with  the RXCOMM and  RXFUNC  command  codes.   It
indicates  that the command or function argument(in slot ARGO)is  a  "string
file" rather than a file name.

RXFF_TOKEN:

This  flag  is used with the RXCOMM code to request that the command  string
be  completely  tokenized  before  being  passed  to  the  invoked  program.
Programs  invoked as commands normally have only a single  argument  string.
The  tokenization  process uses "white space" to separate the  tokens,except
within quoted strings. Quoted strings can use either single or double

208

quotes,and the end of the command string(a null character)  is considered as
an implicit closing quote

ReplyRexxMsg ReplyRexxMsg rexxmsg, Resultl, Result2, "ResultString "

When  ARexx  sends you a RexxMsg (Other than a reply to yours i.e.   sending
yours  back to you with results)  you must repl to the message before  ARexx
will  continue  or  free   that   memory   associated   with  that  RexxMsg.
ReplyRexxMsg accomplishes this for you.  ReplyRexxMsg also will  only  reply
to  message  that  requires a reply so you do not have  to  include  message
checking  routines in your source simply call ReplyRexxMsg on every  message
you receive wether it is a command or not.

The arguments are:

rexxmsg  is  the LONGWORD address of the RexxMsg Arexx sent you as  returned
by GetMsg_(Port).

Result1 is 0 or a severity value if there was an error.

Result2  is 0 or an Arexx error number if there was an error processing  the
command that was contained in the message.

ResultString is the result string to be sent back to Arexx.  This will  only
be sent if Arexx requested one and Resultl and 2 are 0.

ReplyRexxMsg rexxmsg,0,0,"THE RETURNED MESSAGE"

GetRexxResult() Resultl=GetRexxResult(rexxmsg,ResultNum)

GetRexxResult  extracts either of the two result numbers  from  the  RexxMsg
structure. Care must be taken with this Function to ascertain wether you are
dealing with error codes or a ResultString address.  Basically if  result  I
is zero then result 2 will either be zero or contain a ArgString pointer  to
the ResultString. This should then be obtained using GetResultString().

The arguments to GetRexxResult are;

rexxmsg is the LONGWORD address of a RexxMsg structure returned from ARexx.

ResultNum is either I or 2 depending on wether you wish to check result I or
result 2. GetRexxCommand (rexxmsg,ARGnum)

GetRexxCommand  allows you access to all 16 ArgString  slots  in  the  given
RexxMsg.   Slot  I contains the command string sent by ARexx  in  a  command
message so this allows you to extract the Command.

Arguments are:

Page 209

rexxmsg  is  a  LONGWORD  address of the RexxMsg structure  as  returned  by
RexxEvent()

AFGNum is an integer from I to 16 specifying the ArgString Slot you wish  to
get an ArgString from.

YOU MUST KNOW THAT THERE IS AN ARGSTRING THERE.

GetResultString (rexxmag)

GetResultString allows you to extract the result string returned to  you  by
ARexx after it has completed the action you requested.  ARexx will only send
back  a result string if you asked for one (using the ActionCodes)  and  the
requested action was successful.

Wait

Wait  halts all program execution until an event occurs that the program  is
interested in.  Any intuition event such as clicking on a gadget in a window
will start program execution again.

A message arriving at a MsgPort will also start program execution again.  So
you  may use Wait to wait for input from any source including messages  from
ARexx to your program.

Wait  should  always be paired with EVENT if you need to consider  intuition
events in your event handler loop.

RexxEvent (Port)

RexxEvent is our Arexx Equivalent of EVENT().  It's purpose is to check  the
given Port to see if there is a message waiting there for us.

It  should  be called atter a WAIT and will either return a NULL  to  us  if
there  was  no message or the LONG address of a RexxMsg Structure  if  there
was a message waiting.

Multiple  Arexx MsgPorts can be handled using separate calls to RexxEvent():
Wait:Rmsg I .I=RexxEvent(Port I ):Rmsg2.1=RexxEvent(Port2):etc

RexxEvent also takes care of automatically clearing the rexxmsg if it is our
message being returned to us.

The  argument  is  the   LONG   address   of   a   MsgPort  as  returned  by
CreateMsgPort().

IsRexxMsg (rexxmsg)

IsRexxMsg  tests  the argument (a LONGWORD pointer hopefully  to  a  message
packet)  to see if it is a RexxMsg Packet.  If it is TRUE is returned (1) or
FALSE if it is not (0).

As  the  test  is non destructive and extensive passing a NULL  value  or  a
LONGWORD  that  does not point to a Message structure (Intuition  or  Arexx)
will safely return as FALSE.

RexxError() ErrorString$=RexxError(ErrorCode)

RexxError  converts  a  numerical error code such  as  you  would  get  from
GetRexxResult(msg,2)  into an understandable string error message.   If  the
ErrorCode is not known to ARexx a string stating so is returned this ensures
that this function will always succeed.

Page 210

R-29: BREXX COMMANDS

The  Blitz  BRexx commands allow you to take control of certain  aspects  of
Intuition.  Through BRexx,  your programs can 'fool' Intuition into thinking
that the mouse has been played with,  or the keyboard has been used. This is
ideal  for giving your programs the ability to perform 'macros' - where  one
keystroke can set off a chain of pre-defined events.

The BRexx commands support tape objects.  These are predefined sequences  of
events  which may be played back at any time.  The convenient Record command
can be used to easily create tapes.  Using the MacroKey command,  tapes  may
also  be  attached to any keystroke to be played back instantly at the  push
of a button!

Please note that none of the BRexx commands are available in Blitz mode.

AbsMouse X,Y

AbsMouse  allows  you to position the mouse pointer at an  absolute  display
location.  The X parameter specifies how far across the display the  pointer
is  to  be  positioned,  while the Y parameter specifies how  far  down  the
display.  X must be in the range zero through 639.  Y must be in  the  range
zero through 399 for NTSC machines, or zero through 511 for PAL machines.

RelMouse X Offset, Y Offset

RelMouse allows you to move the mouse pointer a relative distance from  it's
current  location.   Positive  offset   parameters  will  move  the  pointer
rightwards  and downwards,  while negative offset parameters will  move  the
pointer leftwards and upwards.

MouseButton Button,Onl Off

MouseButton  allows  you to alter the status of the Amiga's  left  or  right
mouse buttons.  Button should be set to zero to alter the left mouse button,
or  one to alter the right mouse button.  On/Off refers to whether the mouse
button should be pressed (On) or released (Off).

ClickButton Button

ClickButton  is identical to executing two MouseButton commands  -  one  for
pressing the mouse button down,  and one for releasing it.  This can be used
for such things as gadget selection.

Type String$

Type  causes Intution to behave exactly as if a certain series  of  keyboard
characters had been entered. These are normally sent to the currently active
window.

Page 211

Record [Tape#]

Record  allows you to create a tape object.  Tape objects are  sequences  of
mouse and/or keyboard events which may be played back at any time.

When  a  tape# parameter is supplied to the Record command,  recording  will
begin.  From that point on, all mouse and keyboard activity will be recorded
onto the specified tape.

The Record command with no parameters will cause any recording to finish.

PlayBack [Tape#]

PlayBack begins playback of a previously created tape object.  When a  Tape#
parameter is supplied,  playback of the specified tape will commence.  If no
parameter is supplied,  any tape which may be in the process of being played
back will finish.

auickplay Onl Off

QuickPlay will alter the way tapes are played using the PlayBack command. If
QuickPlay is enabled by use of an On parameter,  then all PlayBack  commands
will cause tapes to be played with no delays between actions. This means any
pauses  which may be present in a tape (for instance,  delays between  mouse
movements) will be ignored when it is played back. QuickPlay Off will return
PlayBack  to  it's  default mode of including  all  tape  pauses.   This  is
sometimes  necessary when playing back tapes which must at some  point  wait
for disk access to finish before continuing.

PlayWait

PlayWait  may be used to halt program flow until a PlayBack of  a  tape  has
finished.

XStatus

XStatus  returns  a  value depending upon the current  state  of  the  BRexx
system. Possible return values and their meanings are as follows:

    0    BRexx is currently inactive. No tapes are either being recorded or
        played back.
    l    BRexx is currently in the process of recording a tape.
        This may be due to either the Record or TapeTrap commands.
    2    BRexx is currently playing a tape back.

SaveTape Tape#,Filename$

SaveTape  allows you to save a previously created tape object out  to  disk.
This tape may later be reloaded using LoadTape.

LoadTape Tape#,Filename$

LoadTape allows you to load a tape object previously saved with SaveTape for
use with the PlayBack command.

Page 212

TapeTrap [Tape#]

TapeTrap allows you to record a sequence of AbsMouse,  RelMouse, MouseButton
and ClickButton events to a tape object.

TapeTrap works similarly to Record, in that both commands are used to create
a tape.  However,  whereas Record receives information from the actual mouse
and  keyboard,  TapeTrap receives information from any AbsMouse,   RelMouse,
MouseButton  and ClickButton commands which may be executed.  TapeTrap  with
no parameter wil1 finish tape creation.

QuietTrap Onl Off

QuietTrap determines the way in which any TapeTrapping will be executed.

QuietTrap On will cause any AbsMouse,  RelMouse, MouseButton and ClickButton
commands to be recorded to tape,  but not to actually have any effect on the
porgram currently running.

QuietTrap  Off  will  cause  any   AbsMouse,    RelMouse,   MouseButton  and
ClickButton  commands  to be recorded to tape,  AND  to  cause  their  usual
effects. QuietTrap Off is the default mode.

MacroKey Tape#,Rawkey,Qualifier

MacroKey  causes  a  previously defined tape object  to  be  attached  to  a
particular keyboard key. RawKey and Qualifier define the key the tape should
be attached to.

FreeMacroKey Rawkey, Qualifier

FreeMacroKey causes a previously defined macro key to be removed so  that  a
BRexx tape is no longer attatched to it.

Page 213



R-30: SERIAL PORT COMMANDS

The  following are a set of commands to drive both the single  RS232  serial
port  on an Amiga as well as supporting multiserial port cards such  as  the
A2232 card.  The unit# in the following commands should be set to 0 for  the
standard RS232 port,  unit I refers to the default serial port  set  by  the
advanced  serial preferences program and unit 2 refer to  any  extra  serial
ports available.

OpenSerial device$,unit#,baud,io_serfiags

OpenSerial  is  used to configure a Serial Port for use.  As with  OpenFile,
OpenSerial  is  a  function and returns zero if it fails.   If  it  succeeds
advanced  users may note the return result is the location of  the  IOExtSer
structure.   The  device$  should be "serial.device"  or  compatible  device
driver.   The  baud  rate  should  be in  the  range  of  110-292,000.   The
io_serflags parameter can include the following flags:

#serf_xdisabled= 128    ;disable xon/xoff
#serf eofmode=64    ;enable eof checking
#serf_shared=32        ;set if you don't need exclusive use of port
#serf rad_boogie= 16    ;high speed mode
#serf_queuedbrk=8    ;if set a break command waits for buffer empty
#serf_7wire=4        ;if set use 7 wire RS232
#serf_parity_odd=2    ;select odd parity (even if not set)
#serf_parity_on= I    ;enable parity checking

WriteSerial unit#,byte

WriteSerial sends one byte to the serial port.  Unit# defines  which  serial
port  is  used.   If you are sending characters use the Asc()   function  to
convert the character to a byte e.g. WriteSerial 0,asc("b").

WriteSerialString unit#,string

WriteSerialString is similar to WriteSerial but sends a complete  string  to
the serial port.

ReadSerial (unit#J

ReadSerial  returns the next byte waiting in the serial port's read  buffer.
If  the  buffer  is empty it returns a -1.  It is best to use  a  word  type
(var.w=ReadSerial(0)) as a byte will not be able to differentiate between -1
and 255.

ReadSerialString (unit#)

ReadSerialString puts the serial port's read buffer into a string,   if  the
buffer is empty the function will return a null string (length=0).

Page 214

CloseSerial unit#

The CloseSerial command will close the port,  enabling other programs to use
it.  Note:  Blitz will automatically close all ports that are opened when  a
program ends.

SetSerialBuffer unit#,bufferlength

SetSerialBuffer  changes the size of the ports read  buffer.   This  may  be
useful  if  your  program is not always handling  serial  port  data  or  is
receiving  and processing large chunks of data.  The smallest size  for  the
internal serial port (unit#0)  is 64 bytes.  The bufferlength variable is in
bytes.

SetSerialLens unit#, readlen, writelen,stopOits

SetSerialLens allows you to change the size of characters read  and  written
by  the  serial  device.  Generally readlen=writelen and should  be  set  to
either 7 or 8, stopbits should be set to I or 2. Default values are 8,8,1.

SetSerialParams unit#

For  advanced users,  SetSerialParams tells the serial port when  parameters
are  changed  This  would only be necesary if they were  changed  by  poking
offsets from IOExtSer which is returned by the OpenSerial command.

SerialEvent (unit#)

SerialEvent is used when your program is handling events from  more  than  I
source, Windows, ARexx etc. This command is currently not implemented

ReadSerialMem Unit#,Address,Length

ReadSerialMem  will fill the given memory space with  data  from  the  given
serial port.

WriteSerial Mem Unit#,Address, Length

WriteSerialMem sends out the given memory space out the given serial port.

Page 215

APPENDIX 1: COMPILE TIME ERRORS

The  following  is a list of all the Blitz 2 compile time errors.   Blitz  2
will  print  these messages when unable to compile a line of your  code  and
fails.   The cursor will be placed on the line with the offending  error  in
most cases.

Sometimes  the  cause  of the error will not be directly  related  to  where
Blitz 2 ceased compiling.  Any reference to an include file or a macro could
mean the error is there and not on the line referenced.

General Syntax Errors

Syntax  Error:   Check for typing mistakes and check your  syntax  with  the
reference manual.

Garbage at End of Line:  A syntax error of sorts.  Causes are usually  typos
and  missing semi colons from the beginning of Remarks.  Also a .type suffix
when accessing NewType items will generate this error.

Numeric  Over  Flow:  The signed value is too large to fit in  the  variable
space provided,  if you need bytes to hold 0..255 rather than -128..127  etc
turn  off  Overflow checking in the runtime errors section  of  the  Options
requester.

Bad  Data:  The values following the Data.type statement are not of the same
type as precedes the Data statement.

Procedure Related Errors

Not  Enough  Parameters:  The command,  statement  or  function  needs  more
parameters.  Use the HELP key for correct number and meaning  of  parameters
with  Blitz][ commands and check Statement and Function definitions in  your
code.

Duplicate parameter variable:  Parmaters listed in statements and  functions
must be unique.

Too  many  parameters:  The statement or function was defined  needing  less
parameters than supplied by the calling routine.

Yllegal Parameter Type: NewTypes cannot be passed to procedures.

Illegal  Procedure return:  The statement or function return is syntatically
incorrect.

Illegal  End  Procedure:   The  statement or function  end  is  syntatically
incorrect.

Shared  outside  of  Procedure:  Shared variables  are  only  applicable  to
procedures.

Page 217

Variable already Shared: Shared variables must be unique in name.

Can't Nest Procedures: Procedures may NOT be defined within procedures, only
from the primary code.

Can't Dim Globals in Procedures:  Global arrays may be only defined from the
pumary code.

Can't  Goto/Gosub  a  Procedure:  Goto and Gosub must  always  point  to  an
existing part of the primary code.

Duplicate Procedure name:  A procedure (statement or function)  of the  same
name has been defined previously in the source.

Procedure  not  found:  The statement or function has  not  previously  been
defined in the source code.

Unterminated  Procedure:  The End Function or End  Statement  commands  must
terminate a procedure definition.

Illegal  Procedure  Call:  The statement or function  call  is  syntatically
incorrect.

Illegal Local Name: Not a valid variable name.

Constants Related Errors

Can't Assign Constant: Constant values can only be assigned to constants, no
variables please.

Constant  not  defined:  A constant (such as #num)   has  been  used  in  an
expression without first being defined

Constant already defined:  Constants can only be defined once,  i.e.  cannot
change their value through the code.

Illegal Constant: Same as can't assign constant

Fractions  Not  allowed in Constants:  Blitz 2 constants  can  only  contain
absolute values, they are usually rounded and no error is generated.

Can't Use Constant: Caused by a clash in constant name definitions.

Constant  Not  Found:  The Constant has not been defined previously  in  the
source code.

Illegal Constant Expression:  A constant may only hold whole numbers, either
a  decimal place,  text or a variable name has been included in the constant
definition.

Page 218

Expression Evaluation Errors

Can't  Assign  Expression:   The  expression  cannot  be  evaluated  or  the
evaluation has generated a value that is incompatible with the equate.

No Terminating Quote: Any text assigns should start and end with quotes.

Precedence  Stack  Overflow:  You have attained an  unprecedented  level  of
complexity  in  your  expression  and  the  Blitz  2  evaluation  stack  has
overflowed. A rare beast indeed!

Illegal Errors

Illegal Trap Vector: The 68000 has only 16 trap vectors.

Illegal Immediate Value:  An immediate value must be a constant and must  be
in range. See the 68000 appendix for immediate value ranges.

Iligeal  Absolute:  The Absolute location specified must be defined  and  in
range.

Illegal  Displacement:  The Displacement location specified must be  defined
and in range.

Illegal Assembler Instruction Size:  The Intstruction size is not available,
refer to the 68000 appendix for relevant instruction sizes.

Illegal Assembler Addressing Mode:  The addressing mode is not available for
that opcode, refer to the 68000 appendix for relevant addressing modes.

Library Based Errors

Illegal  TokeJsr  token  number:  Blitz 2 cannot find  the  library  routine
referred to by the TokeJsr command,  usually caused by the library not being
included  in  DefLibs,   not  present in the BlitzLibs:   directory  or  the
calculation being wrong (token number = libnumber* 128 + token offset).

Library not Found:  'library number': Blitz2 cannot find the library routine
referred to by a Token,  usually caused by the library not being'included in
DeflLibs or the library not present in the BlitzLibs: directories.

Token Not Found:  'token number':  When loading source, Blitz 2 replaces any
unfound  tokens with ?????,  compiling your code with these  unknown  tokens
present will generate the above error.

Page 219

Include Errors

Already Included:  The same source code has already been included previously
in the code.

Can't  open  Include:   Blitz 2 cannot find the  include  file,   check  the
pathname.

Error Reading File: DOS has generated an error during an include.

Program Flow Based Errors

Illegal Else in While Block:  See the reference section for the correct  use
of the Else command with While..Wend blocks.

Until  without Repeat:  Repeat..Until is a block directive and both must  be
present.

Repeat Block too large:  A Repeat..Until block is limited to 32000 bytes  in
length.

Repeat without Until:  Repeat..Until is a block directive and both  must  be
present.

If  Block too Large:  Blitz 2 has a limit of 32K for any blocks of code such
as IF..ENDIF blocks.

If Without End If:  The IF statement has two forms, if the THEN statement is
not  present then and END IF statment must be present to specify the end  of
the block.

Duplicate For...Next Error:  The same variable has been used for a For..Next
loop that is nested within another For..Next loop.

Bad Type for For...Next: The For..Next variable must be of numeric type.

Next without For:  FOR..NEXT is a block directive and both commands must  be
present.

For...Next Block to Long:  Blitz 2 restricts all blocks of code  to  32K  in
size.

For Without Next:  FOR..NEXT is a block directive and both commands must  be
present.

Page 220

Type Based Errors

Can't  Exchange  different lopes:  The Exchange command can  only  swap  two
variables of the same type.

Can't  Exchange NewTypes:  The Exchange command can not handle  NewTypes  at
present.

Type  too Big:  The unsigned value is too large to fit in the variable space
provided.

Mismatched  Types:   Caused  by  mixing   different  types  illegaly  in  an
evaluation.

[ype Mismatch: Same as Mismatched Types.

Can't  Compare Types:  Some Types are incompatible with operations  such  as
compares.

Can't  Convert Types:  The two Types are incompatible and  one  can  not  be
converted to the other.

Duplicate Offset (Entry)  Error:  The NewType has two entries  of  the  same
name.

Duplicated Type: A Type already exists with the same name.

End  NewType without NewType:  The NewType..End NewType is a block directive
and both must be present.

Type Not Found: No Type definition exists for the type referred to.

Illegal Type: Not a legal type for that function or statement.

Offset not Found: The offset has not been defined in the NewType definition.
Element isn't a pointer:  The variable used is not a *var type and so cannot
point to another variable.

Illegal Operator for Type: The operator is not suited for the type used.

Too  many  comma's in Let:  The NewType has less entries than the number  of
values listed after the Let.

Can't  use comma in Let:  The variable you are assigning multiple values  is
either  not  a  NewType and cannot hold multiple values or the  NewType  has
only one entry.

Illegal Function Type: A function may not return a NewType.

Page 221

Conditional Compiling Errors

CNIF/CSIF without CEND:  CNIF and CSIF are block directives and a CEND  must
conclude the block.

CEND  without  CNIF/CSIF...:  CNIF..CEND  is  a  block  directive  and  both
commands must be present.

Resident Based Errors

Clash  in Residents:  Residents being very unique animals,  must not include
the same Macro and Constant definitions.

Can't  Load Resident:  Blitz 2 cannot find the Resident file listed  in  the
Options requester. Check the pathname.

Macro Based Errors

Macro Buffer Overflow:  The Options requester in the Blitz 2 menu contains a
macro  buffer size,  increase if this error is ever reported.  May  also  be
caused by a recursive macro call which generates endless code.

Macro  already Defined:  Another macro with the same name has  already  been
defined,   may  have been defined in one of the included resident  files  as
well as somewhere in the source code.

Can't create Macro inside Macro: Macro definitions must occur in the primary
code.

Macro without End Macro: End Macro must end a Macro definition.

Macro  too  Big:   Macro's are limited to the buffer sizes  defined  in  the
Options requester.

Macros Nested too Deep:  Eight levels of macro nesting is available in Blitz
2. Should never happen ! !

Macro not Found:  The macro has not been defined previous to the !macroname{
} call.

Array Errors

Illegal Array type: Should never happen.

Array  not  found:   A variable name followed by parenthises  has  not  been
previously defined as an array.  Other possible mistakes may be the  use  of
brackets instead of curly brackets for macro and procedure calls,   Blitz  2
thinking instead you are referring to an array name.

Page 222

Array is not a List:  A List function has been used on an array that was not
dimensioned as a List Array.

Illegal number of Dimensions: List arrays are limited to single dimensions.

Array already Dim'd: An array may not be re-dimensioned.

Can't Create Variable inside Dim:  An undefined variable has been used for a
dimension parameter with the Dim statement.

Array not yet Dim'd: See Array not found.

Array not Dim'd: See Array not found.

Interupt Based Errors

End SetInt without SetInt:  Setlnt..End SetInt is a block directive and both
commands must be present.

SetInt without End SetInt:  SetInt..End SetInt is a block directive and both
commands must be present.

Can't use SeVClrInt in Local Mode: Error handling can only be defined by the
primary code.

SetErr not allowed in Procedures:  Error handling can only be defined by the
primary code.

Can't use SeVClrlat in Local Mode: Error handling can only be defined by the
primary code.

End Setlnt without SetInt:  SetInt..End SetInt is a block directive and both
commands must be present.

Setlut without End SetInt:  Setlnt..End SetInt is a block directive and both
commands must be present.

Illegally nested Interrupts: Interrupt handlers can obviously not be nested.
Can't nest SetErr: Interrupt handlers can obviously not be nested.

End SetErr without SetErr:  SetErr..End SetErr is a block directive and both
must be present.

Illegal Interrupt Number:  Amiga interrupts are limited from O to 13.  These
interrupts are listed in the Amiga Hardware reference appendix.

Page 223

Label Errors Label reference out of context: Should never happen

Label  has been used as a Constant:  Labels and constants cannot  share  the
same name.

Illegal Label Name:  Refer to the Programming in Blitz2 chapter for  correct
variable nomenclature.

Duplicate  Label:  A label has been defined twice in the same  source  code.
May also occur with macros where a label is not preceded by a \@.

Label not Found: The label has not been defined anywhere in the source code.
Can't Access Label: The label has not been defined in the source code.

Direct Mode Errors

Cont  Option Disabled:  The Enable Continue option in the Runtime errors  of
the Options menu has been disabled.

Cont  only Available in Direct Mode:  Cont can not be called from your  code
only from the direct mode window.

Library  not  Available in Direct Mode:  The library is only available  from
within your code.

Illegal  direct mode command:  Direct mode is unable to execute the  command
entered.

Direct  Mode  Buffer  Overilow:  The ( )ptions menu contains  sizes  of  all
buffers,  if make smallest code is in effect extra buffer memory will not be
available for direct mode.

Can't Create in Direct Mode:  Variables cannot be created using direct mode,
only ones defined by your code are available.

Select... End Select Errors

Select  without End Select:  Select is a block directive and an  End  Select
must conclude the block.

End Select without Select:  Select..End Select is a block directive and both
must be present.

Default  without  Select:   The Default command  is  only  relevant  to  the
Select..End Select block directive.

Previous Case Block too Large:  A Case section in a Select block  is  larger
than 32K.

Page 224

Case  Without Select:  The Case command is only relevant to the  Select..End
Select block directive.

Blitz Mode Errors

Only  Available in Blitz mode:  The command is only available in Blitz mode,
refer to the reference section for Blitz/Amiga valid commands.

Only  Available in Amiga mode:  The command is only available in Amiga mode,
refer to the reference section for Blitz/Amiga valid commands.

Strange Beast Errors

Optimizer Error! - $': This should never happen. Please report.

Expression too Complex: Should never happen. Contact Mark directly.

Not Supported: Should never happen.

Illegal Token: Should never happen.

Page 225

APPENDIX 2: OPERATING SYSTEM CALLS

BLITZLIBS:AMIGALIBS currently supports the EXEC,  DOS,   GRAPHICS  INTUITION
and  DISKFONT amiga libraries.  Parameter details for each command are given
in brackets and are also available via the Blitz 2 keyboard help system.

Each call may be treated as either a command or a function.  Functions  will
always  return  a  long either containing true or false (signifying  if  the
command was successful or failed) or a value relevant to the routine.

The  relative  offsets from the library base and 68000  register  parameters
are  included for the convenience of the assembler programmer.   When  using
library calls an underscore character (_) should follow the token name.

An  asterisk  (*)   precedinu routine names specifies  that  the  calls  are
private and should not be called trom Blitz 2.

EXEC

-30 Supervisor(userFunction)(a5)
---- special patchable hooks to internal exec activity ---
-36 *execPrivate1()()
-42 *execPrivate2()()
-48 *execPrivate3()()
-54 *execPrivate4()()
-60 *execPrivate5()()
-66 *execPrivate6()()
--- module creation ---
-72 InitCode(startClass,version)(dO/d1)
-78 InitStruct(initTable,memory,size)(a1/a2,dO)
-84 MakeLibrary(funcl nit,structl nit,libl nit,dataSize,segList)(aO/a1 /a2,dO/d 1)
-sO MakeFunctions(target,functionArray,funcDispBase)(aO/a1/a2)
-96 FindResident(name)(a1)
-102 InitResident(resident,segList)(a1,d1)
--- diagnoshcs ---
-108 Alert(alertNum)(d7)
-114 Debug(flags)(dO)
--- interrupts ---
-120 Disable()()
-126 Enable()()
-132 Forbid()()
-138 Permit()()
-144 SetSR(newSR,mask)(dO/d1)
-150 SuperState()()
-156 UserState(sysStack)(dO)
-162 SetlntVector(intNumber,interrupt)(dO/a1)
-168 AddlntServer(intNumber,interrupt)(dO/a1)
-174 RemintServer(intNumber,interrupt)(dO/a1)
-180 Cause(interrupt)(a1)
--- memory allocation ---
-186 Al locate (freeList, byteSize ) (aO, dO )
-192 Deallocate(freeList,memoryBlock byteSize)(aO/a1,dO)
-198 AllocMem(byteSize,requirementsj(dO/d1)
-204 AllocAbs(byteSize,location)(dO/a1)
-210 FreeMem(memoryBlock,byteSize)(a1,dO)
-216 AvailMem(requirements)(d1)
-222 AllocEntr,v(entr,v)(aO)

Page 227


-228 FreeEntry(entry)(aO)
--- lists ---
-234 Insert(list,node,pred)(aO/a1/a2)
-240 AddHead(list,node)(aO/a1)
-246 AddTail(list,node)(aO/a1)
-252 Remove(node)(a1)
-258 RemHead(list)(aO)
-264 RemTail(list)(aO)
-270 Enqueue(list,node)(aO/a1)
-276 FindName(list,name)(aO/a1)
--- tasks ---
-282 AddTask(task,initPC,finalPC)(a1/a2/a3)
-288 RemTask(task)(a1)
-294 FindTask(name)(a1)
-300 SetTaskPri(task,priority) (a 1,dO)
-306 SetSignal(newSignals,signalSet)(dO/d1)
-312 SetExcept(newSignals,signalSet)(dO/d1)
-318 Wait(signalSet)(dO)
-324 Signal(task,signalSet)(a1,dO)
-330 AllocSignal(signalNum)(dO)
-336 FreeSignal(signalNum)(dO)
-342 AllocTrap(trapNum)(dO)
-348 FreeT rap (trapN u m) (dO)
--- messages ---
-354 AddPort(port)(a1)
-360 RemPort(port)(a1)
-366 PutMsg(port,message)(aO/a1)
-372 GetMsa(port)(aO)
-378 ReplyMsg(message)(a1)
-384 WaitPort(port)(aO)
-390 FindPort(name)(a1)
--- libraries ---
-396 AddLibrary(library)(a1)
-402 RemLibrary(library)(a1)
-408 OldOpenLibrary(libName)(a1)
-414 CloseLibrary(library)(a1)
-420 SetFunction(library,funcOffset,newFunction)(a1,aO,dO)
-426 SumLibrary(library)(a1)
--- devices ---
-432 AddDevice(device)(a1)
-438 RemDevice(device)(a1)
-444 OpenDevice(devName,unit,ioRequest,flags)(aO,dO/a1,d1)
-450 CloseDevice(ioRequest)(a1)
-456 DolO(ioRequest)(a1)
-462 SendlO(ioRequest)(a1)
-468 ChecklO(ioRequest)(a1)
-474 WaitlO(ioRequest)(a1)
-480 AbortlO(ioRequest)(a1)
--- resources---
-486 AddResource(resource)(a1)
-492 RemResource(resource)(a1)
-498 OpenResource(resName)(a1)
--- private diagnostic support ---
-504 *execPrivate7()()
-510 *execPrivate8()()
-516 *execPrivate9()()
--- misc ---
-522 RawDoFmt(formatString,dataStream,putChProc, putChData)(aO/a1 /a2/a3)
-528 GetCC()()
-534 TypeOfMem(address)(a1)
-540 Procure(semaport,bidMsg)(aO/a1)
-546 Vacate(semaport)(aO)
-552 OpenLibrary(libName,version)(a1,dO)
*** functions in Release 1.2 or higher *^^
--- signal semaphores (note funny registers found in 1.2 or higher)---

Page 228


-558 InitSemaphore(sigSem)(aO)
-564 ObtainSemaphore(sigSem)(aO)
-570 Release Se maphore (si gSem) (aO)
-576 AttemptSemaphore(siqSem)(aO)
-582 ObtainSemaphoreListtsigSem)(aO)
-588 ReleaseSemaphoreList(sigSem)(aO)
-594 FindSemaphore(sigSem)(a1)
-600 AddSemaphore(sigSem)(a1)
-606 RemSemaphore(sigSem)(al)
--- kickmem support ---
-612 SumKickData()()
--- more memory support---
-618 AddMemList(size,attributes,pri,base,name)(dO/d1/d2/aO/al )
-624 CopyMem(source dest,size)(aO/a1 dO)
-630 CopyMemQuick(source,dest,size)(aO/a1,dO)
*** functions in Release 2.0 or higher'''
--- cache ---
-636 CacheClearU()()
-642 CacheClearE(address,length,caches)(aO dO/d1)
-648 CacheControl(cacheBits,cacheMask)(dOid1)
--- misc ---
-654 CreatelORequest(port,size)(aO,dO)
-660 DeletelORequest(iorequest)(aO)
-666 CreateMsgPort()()
-672 DeleteMsgPort(port)(aO)
-678 ObtainSemaphoreShared(sigSem)(aO)
--- even more memory support ---
-684 AllocVec(byteSize,requirements)(dO/d1)
-690 FreeVec(memoryBlock)(a1)
-696 CreatePrivatePool(requirements,puddleSize,puddleThresh)(dO/d1/d2)
-702 Delete Private Pool ( pool H ead er) (aO)
-708 AllocPooled(memSize,poolHeader)(dO/aO)
-714 FreePooled(memory,poolHeader)(a1,aO)
--- misc ---
-720 AttemptSemaphoreShared(sigSem)(aO)
-726 ColdReboot()()
-732 StackSwap(newStack)(aO)
--- task trees ---
-738 ChildFree(tid)(dO)
-744 ChildOrphan(tid)(dO)
-750 ChildStatus(tid)(dO)
-756 ChildWait(tid)(dO)
--- future expansion ---
-762 CachePreDMA(address,length,flags)(aO/a1,d1)
-768 CachePostDMA(address,length,flags)(aO/a1,d1)
-774 *execPrivate10()()
-780 *execPrivate11 ()()
-786 *execPrivate12()()
-792 *execPrivate13()()

DOS
-30 Open(name,accessMode)(d1/d2)
-36 Close(file)(d1)
-42 Read(file,buffer,length)(d1/d2/d3)
-48 Write(file,buffer,length)(d 1 /d2/d3)
-54 input()()
-60 Output()()
-66 Seek(file,position ,offset)(d 1 /d2/d3)
-72 DeleteFile(name)(d1)
-78 Rename(oldName,newName)(d1/d2)
-84 Lock(name,type)(d1/d2)
-90 UnLock(lock)(d1)
-96 DupLock(lock)(d1)
-102 Examine(lock,filelnfoBlock)(d1/d2)

Page 229


-108 ExNext(lock,filelnfoBlock)(d1 /d2)
-114 Info(lock,parameterBlock)(dl/d2)
-120 CreateDir(name)(d1)
-126 CurrentDir(lock)(d1)
-132 loErr()()
-138 CreateProc(name,pri,segList,stackSize)(d1/d2/d3/d4)
-144 Exit(returnCode)(d1)
-150 LoadSeg(name)(d1)
-156 UnLoadSeg(seglist)(d1)
-162 *dosPrivatel ()()
-168 *dosPrivate2()()
-174 DeviceProc(name)(d1)
-180 SetComment(name,comment)(d1/d2)
-186 SetProtection(name,protect)(d1/d2)
-192 DateStamp(date)(d1)
-198 Delay(timeout)(d1)
-204 WaitForChar(file,timeout)(d1/d2)
-210 ParentDir(lock)(d1)
-216 Isinteractive(file)(dl)
-222 Execute(string,file,file2)(d1/d2/d3)
***functions in Release 2.0 or higher'''
---DOS Object creation/deletion---
-228 AllocDosObject(type,tags)(d1/d2)
-234 FreeDosObject(type,ptr)(d 1 /d2)
---Packet Level routines---
-240 DoPkt(port,action,arg1,arg2,arg3,arg4,arg5)(d1/d2/d3/d4/d5/d6/d7)
-246 SendPkt(dp,port,replyport)(d1/d2/d3)
-252 WaitPkt()()
-258 ReplyPkt(dp,res1 res2)(d1 /d2/d3)
-264 AbortPkt(port,pktj(d1/d2)
---Record Locking---
-270 LockRecord(fh,offset,length,mode,timeout)(d1/d2/d3/d4/d5)
-276 LockRecords(recArray,timeout)(d1/d2)
-282 UnLockRecord(fh,offset,length)(d1/d2/d3)
-288 UnLockRecords(recArray)(d1)
---Buffered File l/O---
-294 Selectlnput(fh)(d1)
-300 SelectOutput(fh)(d1)
-306 FGetC(fh)(d1)
-312 FPutC(fh,ch)(d1/d2)
-318 UnGetC(fh,character) (d 1 /d2)
-324 FRead(fh,block,blocklen,number)(d1/d2/d3/d4)
-330 FWrite(fh,block,blocklen,number)(d1/d2/d3/d4)
-336 FGets(fh,buf,buflen)(d1/d2/d3)
-342 FPuts(fh,str)(d1/d2)
-348 VFWritef(fh,format,argarray)(d 1 /d2/d3)
-354 VFPrinff(fh,format,argarray)(d 1 /d2/d3)
-360 Flush(fh)(d1)
-366 SetVBuf(fh,buff,type,size) (d 1 /d2/d3/d4)
---DOS Object Management---
-372 DupLockFromFH(fh)(d1)
-378 OpenFromLock(lock)(d1)
-384 ParentOfFH(fh)(d1)
-390 ExamineFH(fh,fib)(d1/d2)
-396 SetFileDate(name,date)(d1/d2)
-402 NameFromLock(lock,buffer,len)(d 1 /d2/d3)
-408 NameFromFH(fh,buffer,len)(d1/d2/d3)
-414 SplitName(name,seperator buf,oldpos,size)(d1/d2/d3/d4/d5)
-420 SameLock(iock1,iock2)(d1id2)
-426 SetMode(fh,mode)(d1/d2)
-432 ExAll(lock,buffer,size,data,control)(d1/d2/d3/d4/d5)
-438 Read Li nk(port, lock , path , buffe r,size) (d 1 Id21d31d41d5 )
-444 MakeLink(name,dest,soft) (d 1 /d21d3)
-450 ChangeMode(type,fh,newmode)(d1/d2/d3)
-456 SetFileSize(f h,pos,mode)(d 1 /d2/d3)

Page 230


---Error Handling---
-462 SetloErr(result)(d1)
-468 Fault(code,header,buffer,len)(d 1 /d21d3/d4)
-474 PrintFault(code,header)(d1/d2)
-480 ErrorReport(code,type,arg 1,device)(d 1 /d2/d3/d4)
-486 RESERVED
---Process Management---
-492 Cli()()
-498 CreateNewProc(tags)(d1)
-504 RunCommand(seg,stack,paramptr,paramlen)(d1/d2/d3/d4)
-510 GetConsoleTask()()
-516 SetConsoleTask(task)(d1)
-522 GetFileSysTask()()
-528 SetFileSysTask(task)(d1)
-534 GetArgStr()()
-540 SetArgStr(string)(d1)
-546 FindCliProc(num)(d1)
-552 MaxCli()()
-558 SetCurrentDirName(name)(d1)
-564 GetCurrentDirName(buf,len)(d1/d2)
-570 SetProgramName(name)(d1)
-576 GetProgramName(buf,len)(d 1 /d2)
-582 SetPrompt(name)(d1)
-588 GetPrompt(buf,len)(d1/d2)
-594 SetProgramDir(lock)(d1)
-600 GetProgramDir()()
---Device List Management---
-606 SystemTaqList(command tags)(d1/d2)
-612 AssignLock(name,lock)(di /d2)
-618 AssignLate(name,path)(d1 /d2)
-624 AssignPath(name,path)(d1/d2)
-630 AssignAdd(name,lock)(d1/d2)
-636 RemAssignList(name,lock)(d1/d2)
-642 GetDeviceProc(name dp)(d1/d2)
-648 Free Device Proc(dp)(di )
-654 LockDosList(flags)(d1)
-660 UnLockDosList(flags)(d1)
-666 AttemptLockDosList(flags)(d1)
-672 RemDosEntry(dlist)(d1)
-678 AddDosEntry(dlist)(d1)
-684 FindDosEntry(dlist,name,flags)(d1/d2/d3)
-690 NextDosEntry(dlist,flags)(d1/d2)
-696 MakeDosEntry(name,type)(d1/d2)
-702 FreeDosEntry(dlist)(d1)
-708 IsFileSystem(name)(d1)
---Handler Interface---
-714 Format(filesystem,volumename,dostype)(d1/d2/d3)
-720 Relabel(drive,newname)(d1/d2)
-726 Inhibit(name onoff)(d1/d2)
-732 AddBuffers(name,number)(d 1 /d2)
---Date, Time Routines---
-738 CompareDates(date1,date2)(d1/d2)
-744 DateToStr(datetime)(d1)
-750 StrToDate(datetime)(d1)
---Image Management---
-756 InternalLoadSeg(f h ,table,funcarray,stack)(dO/aO/a1 /a2)
-762 InternalUnLoadSeg(seglist,freefunc)(d1/a1)
-768 NewLoadSeg(fiie,tags)(d1/d2)
-774 Add Segment(name, seg, system ) (d 1 /d2/d3)
-780 FindSegment(name,seg,system)(d1/d2/d3)
-786 RemSegment(seg)(d1)
---Command Support----
-792 CheckSignal(mask)(d1)
-798 ReadArgs(template,array,args)(d1/d2/d3)
-804 FindArg(keyword,template)(d1/d2)

Page 231


-810 Readltem(name,maxchars,cSource)(d1/d2/d3)
-816 StrToLong(string,value)(d1 /d2)
-822 MatchFirst(pat,anchor)(d1/d2)
-828 MatchNext(anchor)(d1)
-834 MatchEnd(anchor)(d1)
-840 Parse Patte rn (pat, buf, bufl en ) (d 1 /d 2/d3)
-846 Match Patte rn (pat, str) (d 1 /d2)
-852 * Not currently implemented.
-858 FreeArgs(args)(d1)
-864'--- (1 function slot reserved here) ---
-870 FilePart(path)(d1)
-876 PathPart(path)(d1)
-882 AddPart(dirname,filename,size)(d1/d2/d3)
---Notification---
-888 StartNotify(notify)(d1)
-894 EndNotify(notify)(d1)
---Environment Variable functions---
-900 SetVar(name buffer,size,flags)(d1/d2/d3/d4)
-906 GetVar(name buffer,size,flags)(d1/d2/d3/d4)
-912 DeleteVar(name,flags)(d1/d2)
-918 FindVar(name,type)(d1/d2)
-924 *dosPrivate4()()
-930 ClilnitNewcli(dp)(aO)
-936 ClilnitRun(dp)(aO)
-942 WriteChars(buf,buflen)(d 1 /d2)
-948 PutStr(str)(d1)
-954 VPrinff(format,argarray)(d 1 /d2)
-960 *--- (1 function slot reserved here) ---
-966 ParsePatternNoCase(pat,buf,buflen)(d1/d2/d3)
-972 MatchPatternNoCase(pat,str)(d1/d2)
-978 dosPrivate5()()
-984 SameDevice(lock1,1Ock2)(d1/d2)

GRAPHICS

-30 BltBitMap
(srcBitMap,xSrc,ySrc,destBitMap,xDest,yDest,xSizelySizelminterm,mask,tempA)
(aO,dO/d 1 /a1,d2/d3/d4/d5/d6/d7/a2)
-36
BltTemplate(source,xSrc,srcMod,destRP,xDest,yDest,xSizelySize)(aO,dO/d1 /a1,d2/d3/d4/dS)
--- Text routnes ---
-42 ClearEOL(rp)(a1)
-48 ClearScreen(rp)(a1)
-54 TextLength(rp,string,count)(a1,aO,dO)
-60 Text(rp,string,count)(a1,aO,dO)
-66 SetFont(rp,textFont)(a1,aO)
-72 OpenFont(textAttr)(aO)
-78 CloseFont(textFont)(a1)
-84 AskSoflStyle(rp)(a1)
-90 SetSoffStyle(rp,style,enable)(a1,dO/d1)
--- Gels routnes ---
-96 AddBob(bob,rp)(aO/a1)
-102 AddVSprite(vSprite,rp)(aO/a1)
-108 DoCollision(rp)(a1)
-114 DrawGList(rp,vp)(a1,aO)
-120 InitGels(head,tail,gelsinfo)(aO/a1/a2)
-126 initMasks(vSprite)(a0)
-132 RemlBob(bob,rp,vp)(aO/a1/a2)
-138 RemVSprite(vSprite)(aO)
-144 SetCollision(num,routine,gelsinfo)(dO/aO/a1)
-150 SortGList(rp)(a1)
-156 AddAnimOb(anOb,anKey,rp)(aO/a1 /a2)
-162 Animate(anKey,rp)(aO/a1)
-168 GetGBuffers(anOb,rp,flag)(aO/a1,dO)

Page 232


-174 InitGMasks(anOb)(aO)
--- General graphics routines ---
-180 DrawEllipse(rp,xCenter,yCenter,a,b)(a1,dO/d1/d2/d3)
-186 AreaEllipse(rp,xCenter,yCenter,a,b)(a1,dO/d1 /d2/d3)
-192 LoadRGB4(vp,colors,count)(aO/a1,dO)
-198 InitRastPort(rp)(a1)
-204 InitVPort(vp)(aO)
-210 MrgCop(view)(a1)
-216 MakeVPort(view,vp)(aO/a1)
-222 LoadView(view)(a1)
-228 WaitBlit()()
-234 SetRast(rp,pen)(a1,dO)
-240 Move(rp,x,y)(a1,dO/d1)
-246 Draw(rp,x,y)(a1,dO/d1)
-252 AreaMove(rp x y)(a1 dO/d1)
-258 AreaDraw(rp x y)(a1 dO/d1)
-264 AreaEnd(rp)(a1)
-270 WaitTOF()()
-276 QBlit(blit)(al )
-282 InitArea(arealnfo,vectorBuffer maxVectors)(aO/al,dO)
-288 SetRGB4(vp,index,red,green,blue)(aO,dOld11d21d3)
-294 QBSBlit(blit)(a1)
-300 BltClear(memBlock,byteCount,flags)(a1,dO/d1)
-306 RectFill(rp,xMin,yMin,xMax,yMax)(a1,dO/d1/d2/d3)
-312 BltPattern(rp,mask xMin,yMin,xMax,yMax,maskBPR)(a1,aO,dO/d1 /d2/d3/d4)
-318 ReadPixel(rp,x,y)(a1,dO/d1)
-324 WritePixel(rp,x,y)(a1,dO/d1)
-330 Flood(rp,mode,x,y)(a1,d2,dO/d1)
-336 PolyDraw(rp,count,polyTable)(al,dO/aO)
-342 SetAPen(rp,pen)(al,dO)
-348 SetBPen(rp,pen)(a1,dO)
-354 SetDrMd(rp,drawMode)(a1,dO)
-360 InitView(view)(a1)
-366 CBump(copList)(a1)
-372 CMove(copList,destination,data)(a1,dO/d1)
-378 CWait(copList v,h)(a1,dO/d1)
-384 VBeamPos()(j
-390 InitBitMap(bitMap,depth,width,height)(aO,dO/d1/d2)
-396 ScrollRaster(rp,dx,dy,xMin,yMin,xMax,yMax)(a1,dO/d1/d2/d3/d4/d5)
-402 WaitBOVP(vp)(aO)
-408 GetSprite(sprite,num)(aO,dO)
-414 FreeSprite(num)(dO)
-420 ChanueSprite(vp,sprite,newData)(aO/a1/a2)
-426 MoveSprite(vp,sprite,x,y)(aO/a1,dO/d1)
-432 LockLayerRom(layer) (a5)
-438 UnlockLayerRom(layer)(a5)
-444 SyncSBitMap(layer)(aO)
-450 CopySBitMap(layer)(aO)
-456 OwnBlitter()()
-462 DisownBlitter()()
-468 InitTmpRas(tmpRas,buffer,size)(aO/al,dO)
-474 AskFont(rp ,textAttr) (al ,aO)
-480 AddFont(textFont)(a1)
-486 RemFont(textFont)(a1)
-492 AllocRaster(width,height) (dO/d 1)
-498 FreeRaster(p,width,height)(aO,dO/d1)
-504 AndRectRegion(region,rectangle)(aO/a1)
-510 OrRectRegion(region,rectangle)(aO/a1)
-516 NewRegion()()
-522 ClearRectRegion(region,rectangle)(aO/a1)
-528 ClearRegion(region)(aO)
-534 Di spos e Reg i on ( region ) (aO)
-540 FreeVPortCopLists(vp)(aO)
-546 FreeCopList(copList)(aO)

Page 233


-552
ClipBlit(srcRP,xSrc,ySrc,destRP,xDest,yDest,xSizelySizelminterm)(aO,dO/d1/a1,d2/d3/d4/d5/d6)
-558 XorRectRegion(region,rectangle)(aO/a1)
-564 FreeCprList(cprList)(aO)
-570 GetColorMap(entries)(dO)
-576 FreeColorMap(colorMap)(aO)
-582 GetRGB4(colorMap,entry)(aO,dO)
-588 ScrollVPort(vp)(aO)
-594 UCopperListlnit(uCopList,n)(aO dO)
-600 FreeGBuffers(anOb,rp,flag)(aOial,dO)
-606 BltBitMapRastPort(stcBM,x,y,destRP,x,y,Wld,Height,minterm)(aO,dO/d1/al,d2/d3/d4/d5/d6)
-612 OrRegionRegion(srcRegion,destRegion)(aO/a1)
-618 XorRegionRegion(srcRegion,destRegion)(aO/a1)
-624 AndRegionRegion(srcRegion,destRegion)(aO/a1)
-630 SetRGB4CM(colorMap,index,red,green,blue)(aO,dO/d1/d2/d3)
-636 BltMaskBitMapRastPort

    (srcBM,x,y,destRP,x,y,Wid,High,mterm,Mask)(aO,dO/d1/a1,d2/d3/d4/d5/d6/a2)
-642 RESERVED
-648 RESERVED
-654 AttemptLockLayerRom(layer)(a5)
*** functions in Release 2.0 or higher *-A
-660 GfxNew(gfxNodeType)(dO)
-666 GfxFree(gfxNodePtr)(aO)
-672 GfxAssociate(associateNode,gfxNodePtr)(aO/a1)
-678 BitMapScale(bitScaleArgs)(aO)
-684 ScalerDiv(factor,numerator,denominator)(dO/d1/d2)
-690 TextFit
(rp,string,strLen,textExtent,constrainingExtent,strDirection,constrainingBitWidth,constrainingBitH
eight)(a1,aO,dO/a2)

INTUITION

-30 Openintuition()()
-36 Intuition(iEvent)(aO)
-42 AddGadget(window,gadget,position)(aO/a1,dO)
-48 ClearDMRequest(window)(aO)
-54 ClearMenuStrip(window)(aO)
-60 ClearPointer(window) (aO)
-66 CloseScreen(screen)(aO)
-72 CloseWindow(window)(aO)
-78 CloseWorkBench()()
-84 CurrentTime(seconds,micros)(aO/a1)
-90 DisplayAlert(alertNumber,string,height)(dO/aO,d1)
-96 DisplayBeep(screen)(aO)
-102 DoubleClick(sSeconds,sMicros,cSeconds,cMicros)(dO/d1/d2/d3)
- 108 DrawBorder(rp, border,leftOffset,topOffset)(aO/a 1,dO/d 1)
-114 Drawlmage(rp,image,leftOffset topOffset)(aO/a1,dO/d1)
-120 EndRequest(requester,windowj(aO/a1)
-126 GetDefPrefs(preferences,size)(aO,dO)
-132 GetPrefs(preferences,size)(aO,dO)
-138 InitRequester(requester)(aO)
-144 ItemAddress(menuStrip,menuNumber)(aO,dO)
-150 ModifylDCMP(window,flags)(aO,dO)
-156 ModifyProp
(gadget,window, requester,flags,horizPot, vertPot,horizBody,vertBody)(aO/a1 /a2,dO/d 1 /d2/d3/d4)
-162 MoveScreen(screen,dx dy)(aO,dO/d1)
-168 MoveWindow(window,dx,dy)(aO,dO/d1)
-174 OffGadget(gadget,window,requester)(aO/a1 /a2)
-180 OffMenu(window,menuNumber)(aO,dO)
-186 OnGadget(gadget,window,requester)(aO/a1 /a2)
-192 OnMenu(window,menuNumber)(aO,dO)
-198 OpenScreen(newScreen)(aO)
-204 OpenWindow(newWindow) (aO)
-210 OpenWorkBench()()

Page 234


-216 PrintlText(rp,iText,left,top)(aO/a1,dO/d1)
-222 RefreshGadgets(gadgets,window,requester)(aO/a1/a2)
-228 RemoveGadget(window,gadget)(aO/a1 )
-234 ReportMouse(flag,window)(dO/aO)
-240 Request(requester,window)(aO/a1 )
-246 ScreenToBack(screen)(aO)
-252 ScreenToFront(screen)(aO)
-258 SetDMRequest(window,requester) (aO/a1 )
-264 SetMenuStrip(window,menu)(aO/a1 )
-270 SetPointer(window,pointer,height,width,xOffset,yOffset)(aO/al,dO/d1/d2/d3)
-276 SetWindowTitles(window,windowTitle,screenTitle) (aO/a1 /a2)
-282 ShowTitle(screen showlt)(aO,dO)
-288 SizeWindow(winjow,dx,dy)(aO,dO/d1)
-294 ViewAddress()()
-300 ViewPortAddress(window)(aO)
-306 WindowToBack(window)(aO)
-812 WindowToFront(window)(aO)
-318 WindowLimits(window,widthMin,heightMin,widthMax,heightMax)(aO,dO/d1/d2/d3)
-324 SetPrefs(preferences size,inform)(aO,dO/d1 )
-330 I ntuiTextLength(iTextj(aO)
-336 WBenchToBack()()
-342 WBenchToFront()()
-348
AutoRequest(window, body, posText,negText, p Flag,nFlag,width,height) (aO/a1 la2/a3,dO/d 1 /d2/d3)
-354 BeginRef resh(window)(aO)
-360 BuildSysRequest(window,body,posText,negText,flags,width,height)(aO/a1/a2/a3,dO/d1/d2)
-366 End Refresh (wi ndow , complete) (aO , dO)
-372 FreeSvsRequest(window)(aO)
-378 MakeScreen(screen)(aO)
-384 RemakeDisplay()()
-390 RethinkDisplay()()
-396 AllocRemember(rememberKey,size,flags)(aO,dO/d1)
-402 AlohaWorkbench(wbport)(aO)
-408 FreeRemember(rememberKey,reallyForget)(aO,dO)
-414 Lock l Base (dontknow) (dO )
-420 UnlocklBase(ibLock)(aO)
*** functions in Release 1.2 or higher ***
-426 GetScreenData(buffer,size,type,screen)(aO,dO/d1/a1)
-432 RefreshGList(gadgets,window,requester,numGad)(aO/a1/a2,dO)
-438 AddGList(window,gadget,position,numGad,requester)(aO/a1,dO/d1/a2)
-444 RemoveGList(remPtr,gadget,numGad)(aO/a1,dO)
-450 ActivateWindow(window)(aO)
-456 RefreshWindowFrame(window)(aO)
-462 ActivateGadget(gadgets,window,requester)(aO/a1/a2)
-468 NewModifyProp
(gadget,window,requester,flags,horizPot,vertPot,horizBody,vertBody,numGad)
(aO/a1 /a2,dO/d1 Id21d31d41d5)
*** functions in Release 2.0 or higher *'*
-474 QueryOverscan(displaylD,rect,oScanType)(aO/a1,dO)
-480 MoveWindowlnFrontOf(window,behindWindow)(aO/a1)
-486 ChangeWindowBox(window, left,top,width, height)(aO,dO/d 1 /d2/d3)
-492 SetEditHook(hook)(aO)
-498 SetMouseQueue(window,queueLength)(aO,dO)
-504 ZipWindow(window)(aO)
--- public screens ---
-510 LockPubScreen(name)(aO)
-516 UnlockPubScreen(name,screen)(aO/a1)
-522 LockPubScreenList()()
-528 UnlockPubScreenList()()
-534 NextPubScreen(screen,namebuf)(aO/a1)
-540 SetDefaultPubScreen(name)(aO)
-546 SetPubScreenModes(modes)(dO)
-552 PubScreen Status (screen , status Flags) (aO , dO)
-558 ObtainGIRPort(ginfo)(aO)
-564 ReleaseGIRPort(rp)(aO)

Page 235


-570 GadgetMouse(gadget,ginfo,mousePoint)(aO/a1/a2)
-576 *intuitionPrivatel ()()
-582 GetDefaultPubScreen(nameBuffer)(aO)
-588 EasyRequestArgs(window,easyStruct,idcmpPtr,args)(aOlal/a21a3)
-594 BuildEasyRequestArgs(window,easyStruct,idcmp args)(aO/al,dO/a3)
-600 SysReqHandler(window,idcmpPtr,waitinput)(aO/a;,dO)
-606 OpenWindowTaaList(newWindow,tagList) (aO/al )
-612 OpenScreenTagtist(newScreen,tagList)(aO/a1)
---new Image functions---
-618 DrawimageState(rplimage,leftOffset,topOffset,state,drawinfo)(aO/a1,dO/d1 Id21a2)
-624 Pointinimage(point,image)(dO/aO)
-630 Erasel mage( rp, image, leftOffset,topOffset) (aO/a 1,dO/d 1)
-636 NewObjectA(classPtr classlD,tagList)(aO/a1/a2)
-642 DisposeObject(objectj(aO)
-648 SetAttrsA(object,tagList)(aO/a1)
-654 GetAttr(attrlD,object,storagePtr)(dO/aO/a1)
---special set attribute call for gadgets---
-660 SetGadgetAttrsA(gadget,window, requester,tagList)(aO/a1 /a2/a3)
-666 NextObject(objectPtrPtr)(aO)
-672 *intuitionPrivate2()()
-678 MakeClass(classlD,superClasslD,superClassPtr,instanceSize,flags)(aO/a1/a2,dO/d1)
-684 AddClass(classPtr)(aO)
-690 GetScreenDrawinfo(screen)(aO)
-696 FreeScreenDrawinfo(screen,drawinfo)(aO/a1)
-702 ResetMenuStrip(window menu)(aO/a1)
-708 RemoveClass(classPtr)(aO)
-714 FreeClass(classPtr)(aO)
-720 *intuitionPrivate3()()
-726 *intuitionPrivate4()()

DISKFONT

-30 OpenDiskFont(textAttr)(aO)
-36 AvailFonts(buffer,bufBytes,flags)(aO,dO/d1)
***functions in Release 1.2 or higher'''
-42 NewFontContents(fontsLock,fontName) (aO/a 1)
-48 DisposeFontContents(fontContentsHeader)(a1)
*** functions in Release 2.0 or higher'''
-54 N ewScal ed Di sk Font(sou rce Font, destTe xtAttr) (aO/a 1)

Page 236


APPENDIX 3: AMIGA HARDWARE REGISTERS

The following are a list of memory locations where direct access to the Agnus, Denise
and Paula chips is possible. It is illegal to access any of these registers if you wish
your program to behave correctly in the Amiga environment. However in BlitzMode
most of these registers may be accessed taking into consideration the accompanying
documentation.

An * next to any description states that the option is available only with the new ECS
(Enhanced Chip Set). Also note that any reference to memory pointers MUST point
to chip rnem as the Amiga Chip Set is NOT capable of accessing FAST mem. This
includes BitPlane data, copper lists, Sprite Data, Sound DATA etc. etc.

BitPlane & Display Control

The Amiga has great flexibility in displaying graphics at different resolutions and
positions on the monitor. The hardware registers associated with the display are
nearly always loaded by the copper and not with the 68000 processor.

    #BPLCONO=$1 oo
    #BPLCON 1=$1 02
    #BPLCON2=$1 04
    #BPLCON3=$106    ;(ECS only)
    #BPLCON4=$10c    ;(AGA only)

BIT#    BPLCONO        BPLCON1        BPLCON2        BPLCON3        BPLCON4
15    HIRES        PF2H3        COLBANK2    BPLAM7
14    BPU2        ZDBPSEL2    COLBANK1    BPLAM6
13    BPU1        ZDBPSEL1    COLBANK0    BPLAM5
12    BPUO        ZDBPSELO    PF20F2        BPLAM4
11    HAM        ZDPEN        PF20F1        BPLAM3
10    DBLPF        ZDCTEN        PF20FO        BPLAM2
09    COLOR        KILLEHB        LOCT        BPLAM 1
08    GAUD        RDRAM=0        BPLAMO
07    PF2H3        SOGEN        SPRES1        ESPRM7
06    *SHRES        PF2H2        PF2PRI        SPRESO        ESPRM6
05    *BPLHWRM    PF2H1        PF2P2        BRDRBLNK    ESPRM5
04    *SPRHWRM    PF2H0        PF2P1        BRDRTRAN    ESPRM4
03    LPEN        PF1H3        PF2PO        OSPRM7
02    LACE        PF1H2        PF1 P2        ZDCLCKEN    OSPRM6
01    ERSY        PF1H1        PF1 P1        BRDSPRT        OSPRM5
00    PF1H0        PF1 PO        EXTBLKEN    OSPRM4

BPUn = number of bitplanes
PFnHn = playfield horizontal positioning
ZD... = genlock enable bits
PFnPn = Playfield priorities
COLBANKn = active color bank in AGA
PF20Fn = color offset for playfield 2 in dpf mode
LOCT = hi/lo nibble select for 24 bit color access
SPRESn = Sprite resolution
BRD... = Border settings
BPLAMx = xor mask for bitplane fetch
ESPRMn = color offset for even sprites


Page 237


#BPLOPTH= $E0    ;BitPlane Pointer 0 High Word
#BPLOPTL= $E2    ;BitPlane Pointer 0 Low Word
#BPL1PTH= $E4
#BPL1 PTL= $E6
#BPL2PTH= $E8
#BPL2PTL= $EA
#BPL3PTH= $EC
#BPL3PTL= $EE
#BPL4PTH= $F0
#BPL4PTL= $F2
#BPL5PTH= $F4
#BPL5PTL= $F6

Each  pair  of  registers  contain an 18  bit  pointer  to  the  address  of
BitPlanex  data in chip memory.  They MUST be reset every frame  usually  by
the copper.

#BPL1MOD=$108  ;BitplaneModulo  for  Odd  Planes  #BPL2MOD=$1  OA  ;Bitplane
Modulo for EvenPlanes

At the end of each display line,  the BPLxMODs are added to the the BitPLane
Pointers so they point to the address of the next line.

#DIWSTOP=$090 ; display window stop
#DIWSTRT=$08E ; display window start

These two registers control the display window size and position. The
following bits are assigned

BIT# 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00
     V7 V6 V5 V4 V3 V2 V1 V0 H7 H6 H5 H4 H3 H2 H1 H0

For DIWSTRT V8=0 & H8=0 restricting it to the upper lett of the screen.  For
DIWSTOP V8=1 & H8=1 restricting it to the lower right of the screen.

#DDFSTOP=$094 ; data fetch stop
#DDFSTRT= $092 ; data fetch stant

The  two  display data fetch registers control when and how many  words  are
fetched from the bitplane for each line of display.

Typical values are as follows:

lores 320 pixels, DDFSTRT & DDFSTOP = $38 & $D0
hires 640 pixels, DDFSTRT & DDFSTOP = $3C & $d4

If smooth scrolling is enabled DDFSTRT should be 2 less than above.

#BPL1 DAT $110 ; BitPlane Data parallel to serial converters
#BPL2DAT $112
#BPL3DAT $114
#BPL4DAT $116
#BPL5DAT $118
#BPL6DAT $11A
These 6 registers receive the DMA data fetched by the BitPlane engine,   and
output it serially to the Amiga DACS,  triggered by writing to BPLIDAT.  Not
intended for programmer access.

Page 238

The Copper

The  Copper  is found on the Agnus chip,  it's main job is to 'poke'  values
into the hardware registers in sync with the video beam.  The main registers
it updates are BitPlane ptrs,  Sprites and other control words that HAVE  to
be  reset every frame.  It's also used to split the screen vertically as  it
is  capable of waiting for certain video beam positions before writing data.
Its  also  capable of waiting for the blister to finish as well as  skipping
instructions if beam position is equal to certain values.

#COP1 LCH=$080
#COP1 LCL=$082

#COP2LCH=$084
#COP2LCL=$086

Each  pair of registers contain an 18 bit pointer to the address of a Copper
List in chip mem.  The Copper will automatically jump to the address in COPI
at  the  beginning of the frame and is able to jump to COP2 if the following
strobe is written to.

#COPJMP1 =$88
#COPJMP2=$8A

When  written  to these addresses cause the copper to jump to the  locations
held  in COP I LC & COP2LC.  The Copper can write to these registers  itself
causing its own indirect jump.

#COPCON=$2E

By  setting  bit  I  of this register the copper is allowed  to  access  the
blister hardware.

The  copper  fetches two words for each instruction from its current  copper
list.  The three instructions it can perform and their relevant bits are  as
follows:

    Bit#    MOVE    WAIT     UNTIL        SKIP         IF

    15    x    RD15    VP7        BFD        VP7        BFD
    14    x    RD14    VP6        VE6        VP6        VE6
    13    x    RD13    VP5        VE5        VP5        VE5
    12    x    RD12    VP4        VE4        VP4        VE4
    11    x    RD11    VP3        VE3        VP3        VE3
    10    x    RD10    VP2        VE2        VP2        VE2
    09    x    RD09    VP1        VE1        VP1        VE1
    08    DAB    RD08    VP0        VE0        VP0        VE0
    07    DA7    RD07    HP8        HE8        HP8        HE8
    06    DA6    RD06    HP7        HE7        HP7        HE7
    05    DA5    RD05    HP6        HE6        HP6        HE6
    04    DA4    RD04    HP5        HE5        HP5        HE5
    03    DA3    RD03    HP4        HE4        HP4        HE4
    02    DA2    R D02    HP3        HE3        HP3        HE3
    01    DA1    RD01    HP2        HE2        HP2        HE2
    00    0    RD00    1        0        1        1

The  MOVE  instruction shifts the value held in RD15-0  to  the  destination
address calculated by $DFF000 +DA8- 1.

The  WAIT  UNTIL  instruction places the copper in a wait  state  until  the
video  beam  position  is  past HP,VP (xy coordinates).   The  Copper  first
logical AIDS (masks) the

Page 239

video  beam with HE,VE before doing the comparison.  If BFD is set then  the
blister must also be finished before the copper will exit its wait state.

The  SKIP  IF  instruction  is  similar to the WAIT  UNTIL  instruction  but
instead  of  placing the copper in a wait state if the video  beam  position
fails the comparison test it skips the next MOVE instruction.

Colour Registers

The following 32 color registers can each represent one of 4096 colors.

#COLO R00=$ 180    #COLO R08=$ 190        #CO LOR 16=$ 1 A0    #COLO R24=$ 1 B0
#COLOR01=$182    #COLOR09=$192        #COLOR17=$1A2        #COLOR25=$1B2
#COLO R02=$184    #COLOR 10=$ 194        #COLOR 18=$1 A4        #COLOR26=$ 1 B4
#COLOR03=$186    #COLOR11=$196        #COLOR19=$1A6        #COLOR27=$1B6
#COLOR04=$ 188    #COLO R 12=$ 198    #COLOR20=$1 A8        #COLOR28=$ 1 B8
#COLO R05=$ 18A    #COLOR 13=$ 19A        #COLOR21 =$1 AA        #COLO R29=$ 1 BA
#COLOR06=$18C    #COLOR14=$19C        #COLOR22=$1AC        # COLOR30=$1BC
#COLOR07=$18E    #COLO R 15=$ 19E    #COLOR23=$1 AE        #COLO R31 =$ 1 BE

The bit usage for each of the 32 colors is:

BIT#  15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00
       x x x x R3 R2 R1 R0 G3 G2 G1 G0 B3 B2 B1 B0

This represents a combination of 16 shades of red, green and blue.

glitter Control

The  glitter is located on the Agnus,  it's main function is to move  blocks
of  data  around chip mem.  It has 3 input channels A,B &  C  and  I  output
channel D.  A simple block move would use I input channel and the  I  output
channel,  taking 4 clock ticks per cycle.  A complex move such as a moving a
shape to a destination with a cookie cut would use all 3 input channels  and
the output channel taking 8 clock ticks per cycle.

The  main  parameters of the blister include the width  and  height  of  the
block  to  be  moved (width is in multiples of words),  a start address  for
each  channel,  a modulo for each channel that is added to their address  at
the  end of each line so they point to the next line,  a logic function that
specifies which input channels data will be sent to the destination channel.
The  following  is  a  table to work out the logic tunction  (known  as  the
minterm) for a blister operation.

    A    B    C    D

    O    O    0    LF0
    O    O    1    LF1
    0    1    0    LF2
    O    1    1    LF3
    1    0    0    LF4
    1    0    1    LF5
    1    1    0    LF6
    1    1    1    LF7

Page 240



If  the  glitter is set up so that channel A points to the cookie,  B points
to  the  shape to be copied and C&D point to the destination bitplane  (such
as how Blitz 2 uses the blister) we would specify the following conditions:

When A is I then make D=B When A is O then make D=C

Using  the  above table we calculate the values of LFO-LF7  when  these  two
conditions are met.  The top line has A=0 so LFO becomes the value in the  C
column which is a 0.  A is O in the first 4 rows so LFO-LF3 all reflect  the
bits in the C column (0l0l)  and A= l in the lower 4 rows so LF4-LF7 reflect
the bits in the B column (001 I ).

This generates a minterm LFO-LF7 of % l O I O I l 00 or in hex $AC.

Note:   read  the values of LF7 to LFO from bottom to top to  calculate  the
correct hexadecimal minterm.

#BLTAPTH= $50
#BLTAPTL= $52

#BLTBPTH= $4C
#BLTBPTL= $4E

#BLTCPTH= $48
#BLTCPTL= $4A

#BLTDPTH= $54
#BLTDPTL= $56

Each  pair  of registers contain an 18 bit pointer to the start  address  of
the 4 blister channels in chip mem.

#BLTAMOD=$64
#BLTBMOD=$62
#BLTCMOD=$60
#BLTDMOD=$66

The  4  modulo values are added to the blister pointers at the end  of  each
line.

#BLTADAT=$74
#BLTBDAT=$72
#BLTCDAT= $70

If  a blister channel is disabled the BLTxDAT register can be loaded with  a
constant value which will remain unchanged during the blit operation.

#BLTAFWM=$44 ; glitter first word mask for source A
#BLTALWM=$46 ; glitter last word mask for source A

During  a  glitter  operation  these two registers  are  used  to  mask  the
contents of BLTADAT for the first and last word of every line.

Page 241


#BLTCONO=$40
#BLTCON1=$42

The following bits in BLTCONO & BLTCON I are as follows.


    BIT#    BLTCONO    BLTCON1

    15    ASH3    BSH3
    14    ASH2    BSH2
    13    ASH1    BSH1
    12    ASHO    BSHO
    11    USEA    x
    10    USEB    x
    09    USEC    x
    08    USED    x
    07    LF7    x
    06    LF6    x
    05    LF5    x
    04    LF4    EFE
    03    LF3    IFE
    02    LF2    FCI
    01    LF1    DESC
    00    LFO    0 (1=line mode)


ASH  is  the  amount that source A is shifted (barrel rolled)  USEX  enables
each  of  the  4  blitter channels LF holds the logic function as  discussed
previously  in  this  section BSH is the amount that  source  B  is  shifted
(barrel  rolled)  EFE is the Exclusive Fill Enable flag IFE is the Inclusive
Fill  Enable  flag FCI is the Fill Carry Input DESC is the  descending  flag
(blitter uses decreasing addressing)  #BLTSIZE=$58 By writing the height and
width  of  the  blit  operation  to  BLTSIZE  the  blitter  will  start  the
operation.  Maxiiiiutii size is 1024 hi-h and 64 words (1024 bits) wide. The
followingdefines bits in BLTZSIZE

BIT#15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00
     h9 h8 h7 h6 h5 h4 h3 h2 hl hO w5 w4 w3 w2 wl wO
#BLTSIZV=$5C ;(ECS ONLY)
#BLTSIZH=$5E ;(ECSONLY)

With  the  new ECS writing to BLTSIZV first and then BLTSZH the blitter  can
operate on blocks as large as 32K x 32K pixels in size.

The  Blitter  is  also  able  to  perform  linedrawing  and  filled  polygon
functions.  Details about using the blitter for these functions can be found
on the exai-nples disk included with Blitz 2.

Page 242

Audio Control

The Amiga has 4 channels of 8 bit audio,  each with their own memory access,
period  and  volume  control.  The following are a list  of  the  applicable
hardware registers.

#AUDOLCH=$AO
#AUDOLCL=$A2
#AUD1LCH=$BO
#AUD1LCL=$B2
#AUD2LCH=$CO
#AUD2LCL=$C2
#AUD3LCH=$DO
#AUD3LCL=$D2

#AUDOLEN=$A4
#AUD1LEN=$B4
#AUD2LEN=$C4
#AUD3LEN=$D4

#AUDOPER=$A6 ;period
#AUD1PER=$B6
#AUD2PER=$C6
#AUD3PER=$D6

#AUDOVOL=$A8
#AUD1VOL=$B8
#AUD2VOL=$C8
#AUD3VOL=$D8

#AUDODAT=$AA
#AUD1DAT=$BA
#AUD2DAT=$CA
#AUD3DAT=$DA

Sprite Control

; pairs of 24 bit memory pointers to audio data in chip mem

;volume registers (0-63)

The  Amiga hardware is capable of displaying eight 4 colour sprites or  four
16  colour sprites.  Standard control of sprites is done by using the copper
to setup the 8 sprite pointers at the beginning of each frame.

#SPROPTH=$120
#SPROPTL=$122
#SPR1PTH=$124
#SPR1PTL=$126
#SPR2PTH=$128
#SPR2PTL=$12A
#SPR3PTH=$12C
#SPR3PTL=$12E
#SPR4PTH=$130
#SPR4PTL=$132
#SPR5PTH=$134
#SPR5PTL=$136
#SPR6PTH=$138
#SPR6PTL=$13A
#SPR7PTH=$13C
#SPR7PTL=$13E

;pairs of 24 bit memory pointers to sprite data in chip mem

The pointers should point to data that begins with two words containing  the
SPRPOS & SPRCTL values tor that sprite,  followed by its image data and with
two null words that terminate the data.

Page 243


    #SPROPOS=$140    #SPROCTL=$142    #SPRODATA=$144 #SPRODATB=$146
    #SPRlPOS=$148    #SPR1CTL=$14A    #SPR1DATA=$14C #SPR1DATB=$14E
    #SPR2POS=$150    #SPR2CTL=$152    #SPR2DATA=$154 #SPR2DATB=$156
    #SPR3POS=$158    #SPR3CTL=$15A    #SPR3DATA=$15C #SPR3DATB=$15E
    #SPR4POS=$160    #SPR4CTL=$162    #SPR4DATA=$164 #SPR4DATB=$166
    #SPR5POS=$168    #SPR5CTL=$16A    #SPR5DATA=$16C #SPR5DATB=$16E
    #SPR6POS=$170    #SPR6CTL=$172    #SPR6DATA=$174 #SPR6DATB=$176
    #SPR7POS=$178    #SPR7CTL=$17A    #SPR7DATA=$17C #SPR7DATB=$17E

Using  standard  sprite DMA the above registers  are  all  loaded  from  the
sprite  data pointed to in chip mem by the sprite pointers.  These registers
are  only of interest to people wanting to 'multiplex' sprites by using  the
copper to load these registers rather than sprite DMA,

The t'ollowing is bit definitions of both SPRPOS and SPRCTL.

    BiT# 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00

POS SV7 SV6 SV5 SV4 SV3 SV2 SV1SV0 SH8 SH7 SH6 SH5 SH4 SH3SH2SH1

    CTL EV7 EV6 EV5 EV4 EV3 EV2 EV1EV0 ATT X X X    X SV8 EV8 SH0

SV  is  the  vertical  start position of the sprite  SH  is  the  horizontal
position  of  the  sprite (calulated in lores pixels  only)   EVis  the  end
vertical  position ATTis the sprite attached bit (connects  odd  sprites  to
their predecessors)

Interupt Control

#INTENA=$9A ;interupt enable write address
#INTENAR=$1C ;interupt enable read address

#INTREQ=$9C ;interupt request write address
#INTREQR=$1E ;interupt request read address

INTENA  is  used  to enable or disable interupts.  If the value  written  to
INTENA  has  bit  15  set  any other of the bits enable their  corresponding
interupts.  If bit 15 is clear any of the other bits set will disable  their
corresponding interupts.

INTENAR will return which interupts are currently enabled.

INTREQ is used to initiate or clear an interupt.  It is mostly used to clear
the  interupt  by  the interupt handler.  Again Bit# 15 states  whether  the
corrsponding interupts will be requested or cleared.

INTREQR returns which interupts are currently requested.

Page 244


The following bit definitions relate to the 4 interupt control registers.

BIT#    NAME        LEVEL    DESCRIPTION

15    SET/CLR            determines if bits written with 1 are set or cleared
14    INTEN            master interupt enable
13    EXTER        6    external interupt
12    DSKSYN        5    disk sync register (same as DSKSYNC)
11    RBF        5    serial port Receive Buffer Full
10    AUD3        4    audio channel 3 finished
09    AUD2        4    audio channel 2 finished
08    AUDI        4    audio channel 1 finished
07    AUD0        4    audio channel 0 finished
06    BLIT        3    blister finished
05    VERTB        3    start of vertical blank interupt
04    COPER        3    copper
03    PORTS        2    I/O ports and timers
02    SOFT        1    reserved for software initiated interupts
01    DSKBLK        1    disk block finished
00    TBE        1    serial port Transmit Buffer Empty


The  following locations hold the address of the 68000 interupt handler code
in memory for each level of interupt.

LEVEL    68000 Address

6        $78
5        $74
4        $70
3        $6c
2        $68
1        $64

DMA Control

DMA  stands  for  direct memory access.  Chip mem can  be  accessed  by  the
display,  blister,  copper,  audio,  sprites and diskdrive without using the
68000  processor.  DMACON enables the user to lock out  any  of  these  from
havidg direct memory access (DMA) to chipmem.

As  with INTENA bit l S of DMACON signals whether the write opertaion should
clear or set the relevant bits of the DMA control.

DMACONR  will not only return which channels have DMA access but  has  flags
BBUSY  which  return  true if the blister is in operation  and  BZERO  which
return  if the glitter has generated any l's from it logic function  (useful
for collision detection etc.)

#DMACON=$96 ;DMA control write (dear or set)  #DMACONR=$02 ;DMA control read
(and blister status) read

Page 245


The following are the bits assigned to the two DMACON registers:

BIT#    NAME        DESCRIPTION

15    SET/CLR        determines if bits written with 1 are set or cleared
14    BBUSY        blister busy flag
13    BZERO        blister logic zero
12    X
11    X
10    BLTPRI        "blister nasty" signals blister has DMA priority over CPU
09    DMAEN        enable all DMA below
08    BPLEN        BitPlane DMA enable
07    COPEN        Copper DMA enable
06    BLTEN        glitter DMA enable
05    SPREN        Sprite DMA enable
04    DSKEN        Disk DMA enable
03    AUD3EN        Audio channel 3 DMA enable
02    AUD2EN        Audio channel 2 DMA enable
01    AUDI EN        Audio channel 1 DMA enable
00    AUDOEN        Audio channel 0 DMA enable

Amiga ClAs

The Amiga has two 8520 Complex Interface Adapter (CIA)  which handle most of
the Amiga I/O activities.  Note that each register should be accessed  as  a
byte and NOT a word. The following is an address map of both Amiga CIAs.

    CIA-A    Address    Register    b7 b6 b5 b4 b3 b2 b1 bO

    $BFE001    pra FIR1 FIR0 RDY TK0 WPR0 CHNG    LED OVL
    $BFE101    prb Parallel Port
    $BFE201    ddra Direction for Port A (1=output)
    $BFE301    ddrb Direction for Port B (1=output)
    $BFE401    talo Timer A High Byte
    $BFE501    tahi Timer A High Byte
    $BFE601    thlo Timer B Low Byte
    $BFE701    tbhi Timer B High Byte
    $BFE801    todlo 50/60 Hz Event Counter bits 7-0
    $BFE901    todmid 50/60 Hz Event Counter bits 15-8
    $BFEA01    todhi 50/60 Hz Event Counter bits 23-16
    $BFEB01    not used

    $BFEC01    sdr    Serial Data Register (connected to keyboard)
    $BFED01    icr    Interrupt Control Register
    $BFEE01    cra    Control Register A
    $BFEF01    crb    Control Register B

    CIA-B    Address    Register    b7 b6 b5 b4 b3 b2 b1 bO
        $BFD000    pra    DTR RTS CD CTS DSR SEL POUT BUSY

        $BFD100    prb MTR SEL3 SEL2 SEL1 SEL0 SIDE DIR    STEP
        $BFD200    ddra Direction for Port A (1=output)
        $BFD300    ddrb Direction for Port B (1=output)
        $BFD400    talo Timer A High Byte
        $BFD500    tahi Timer A High Byte
        $BFD600    tblo Timer B Low Byte
        $BFD700    tbhi Timer B High Byte
        $BFD800    todlo Horizontal Sync Event Counter bits 7-0
        $BFD900    todmid Horizontal Sync Event Counter bits 15-8
        $BFDA00    todhi Horizontal Sync Event Counter bits 23-16
        $BFDB00    not used

        $BFDC00    sdr    Serial Data Register (connected to keyboard)
        $BFDD00    icr    Interrupt Control Register
        $BFDE00    cra    Control Register P
        $BFDF00    crb    Control Register E

Page 246



APPENDIX 4: 68000 ASSEMBLY LANGUAGE
Although Blitz 2 is a BASIC compiler,  it also has an 'inline assembler' and
can be used as a fully fledged assembler.  Assembly language is the language
of the microprocessor, in the case of the Amiga, the 68000 microprocessor.

The  following  is a brief description of the Motorola 68000  microprocessor
and  its instruction set,  for more information we recommend the data  books
published by Motorola themselves as the best source of reference material.

Registers

The 68000 has 1 6 internal registers,  these may be thought of as high speed
variables  each  capable  of storing a long word  (32  bits).   The  8  data
registers  are  used mainly for calculations while the 8  address  registers
are mostly used for pointing to locations in memory.

The  registers  are  named  DO-D7 and AO-A7.  The  68000  also  has  several
speciaiised  registers,  the program counter (PC)  and the  status  register
(SR)   The  program  counter  points to the  current  instruction  that  the
microprocessor is executing,  while the status register is a bunch of  flags
with various meanings.

Addressing

The  main  job  of  the microprocessor is to read information  from  memory,
perform a calculation and then write the result back to memory.

For  the processor to access memory it has to generate a memory address  for
the  location it wishes to access (read or write to)  The foiiowing are  the
different ways the 68000 can generate addresses.

Register Direct:  MOVE d 1,dO The actual value in the register d I is copied
into dO

Address  Register Indirect:  MOVE (aO),dO aO is a pointer  to  somewhere  in
memory. The value at this location is copied into the register dO.

Address  Register Indirect with Postincrement:  MOVE (aO)+,dO The  value  at
the  location pointed to by aO is copied into the register dO,  then  aO  is
incremented so it points to the next memory location.

Address  Register  Indirect with Predecrement:  MOVE -(aO),dO  aO  is  first
decremented  to  point to the memory location before the  one  it  currently
points to then the value at the new memory location is copied into dO.

Address  Register  Indirect with Displacement:  MOVE I 6(aO),dO  The  memory
location  located  16  bytes  after that which  is  pointed  to  by  address
register aO is copied to dO.

Page 247

Address  Register  Indirect with Index:  MOVE I 6(aO,d  1  ),dO  The  memory
location is calculated by adding the contents of aO with d I plus 16.

Absolute Address: MOVE $dff'096,dO The memory location $dff'096 is used.

Program  Counter with Displacement:  MOVE label(pc),dO This is the  same  as
absolute  addressing but because the memory address is an  offset  from  the
program counter (no bigger than 32000 bytes) it is MUCH quicker.

Program Counter with Index:  MOVE label(pc,d I ),dO The address is calulated
as the location of label plus the contents of data register d 1.

Immediate Data: MOVE #20,dO The value 20 is moved to the data register.

Program Flow

As  mentioned previously the microprocessor has a special register known  as
the program counter that points to the next instruction to be executed.   By
changing  the  value in the program counter a 'goto' can be performed.   The
JMP instruction load the program counter with a new value,  it supports most
of the addressing modes.

A  branch  is  a  program  counter relative form  of  the  JMP  instruction.
Branches can also be performed on certain conditions such as BCC which  will
only  cause  the  program flow to change if the Carry  flag  in  the  status
register is currently set.

A  'Gosub''  can be performed using the JSR and BSR commands.   The  current
value  of the program counter is remembered on the stack before the jump  or
branch  is  performed.  The RTS command is used to return  to  the  original
program location.

The Stack

The  Amiga sets aside a certain amount of memory for each task  known  as  a
stack.   The  address register A7 is used to point to the stack  and  should
never be used as a general purpose address register.

The  68000  uses  predicament addressing to push data  onto  the  stack  and
postincrement addressing to pull information off the stack.

JSR is the same as MOVE.I pc,-(a7) and then JMP

RTS is the same as MOVE.I (a7)+,pc

The stack can be used to temporarily store internal registers.  To save  and
restore all the 68000 registers the following code is often used

ASubroutine:  MOVEM.I dO-d7/aO-a6,-(a7)  ,push all register on  stack  ;main
subroutine  code here which can stuff up registers without worrying  MOVEM.I
(a7)+,dO-d7/aO-a6 ;pull registers off stack

RTS ;returnfrom subroutine

Page 248

Condition Flags

The  status register is a special 68000 register that holds,  besides  other
things  all the condition codes.  The following are a list of the  condition
flags:

Code      Name        Meaning

N    negative    reflects the most significant bit of the result of the last operation.
Z    zero        is set if the result is zero, cleared otherwise.
C    carry        is set when an add, subtract or compare operation generate a carry
X    extend        is a mirror of the carry flag, however its not affected by data movement.
V    overf ow    is set when an arithmetic operation causes an overflow, a situation where
                    the operand is not large enough to represent the result.

Conditional Tests

Branches and Sets can be performed conditionally.  The following is  a  list
of  the  possible conditions that can be tested before a branch  or  set  is
performed.

cc    condition        coding        test

T    true            0000        0
F    false            0001        1
HI    high            0010        not C & not Z
LS    lowsam            0011        C | Z
CC    carry clr        0100        not C
CS    carry set        0101        C
NE    not equal        0110        not Z
EQ    equal            0111        Z
VC    overflow clr    1000        not V
VS    overflow set    1001        V
PL    plus            1010        not N
MI    minus            1011        N
GE    greater equal    1100        N&V | notN¬V
LT    less than        1101        N¬V I notN&V
GT    greater than    1110        N&V¬Z I notN¬V¬C
LE    less or equal    1111        Z I N¬V I notN&V

Operand Sizes

The 68000 can perform operations on bytes,  words and long words.  By adding
a suffix .b .w or .l to the opcode,  the assembler knows which data size you
wish to use,  if no suffix is present the word size is default.  There is no
speed  increase  using bytes instead of words as  the  68000  is  a  16  bit
microprocessor and so no overhead is needed for 16 bit operations.   However
32  bit long words do cause overhead with extra read and write cycles needed
to perform operations on a bus that can only handle 16 bits at a time.

Page 249



The 68000 Instruction Set

The following is a brief description of the 68000 instruction set.

Included with each are the addressing mode combinations available with  each
opcode. Their syntax are as follows:

     Dndata register
     Anaddress register
     Dy, Dxdata registers source & destination
     Rx,Ryregister source & destination (data & address registers)
     <ea>effective address - a subset of addressing modes
     #<data>numeric constant

Special notes:

The address register operands ADDA,  CMPA,  MOVEA and SUBA are only word and
long word data sizes.  The last'A'of the operand name is optional as  it  is
with the immediate operands ADDI, CMPI, MOVE], SUBI, ORI, EORI and ANDI.

The ADDQ and SUBQ are quick forms of their immediate cousins.  The immediate
data  range is 1 to 8.  The MOVEQ instruction has a data range  of  -128  to
127,  the data is sign extended to 32 bits,  and long is the only data  size
available.

The  <ea>  denotes  an  effective address,  not  all  addressing  modes  are
available with each effective address form of the instruction,   as  a  rule
program  counter  relative  addressing is  only  available  for  the  source
operand and not the destination.

The  Blitz2 compiler will signal any illegal forms of the instruction during
the compile stage.


    ABCD    Add with extend using BCD
        ABCD Dy,Dx
        ABCD -(Ay),-(Ax)
    ADD    Add binary
        ADD <ea>,Dn
        ADD Dn,<ea>
        ADDA <ea>,An
        ADDI #<data>,<ea>
        ADDO #<data>,<ea>
    ADDX    Add with Extend
        ADDX Dy,Dx
        ADDX -(Ay),-(Ax)
    AND    AND logical
        AND <ea>,Dn
        AND Dn,<ea>
        ANDI #<data>,<ea>
    ASL    Arithmetic Shift Left
        ASL Dx,Dy
        ASL #<data>,Dy
        ASL <ea>
    ASR    Arithmetic Shift Pight
        ASR Dx,Dy
        ASR #<data>,Dy
        ASR <ea>
    Bcc    Branch Conditionally
        Bcd <label>
    BCHG    Test a Bit & Change
        BCHG Dn,<ea>
        BCHG #<data>,<ea>
    BCLR    Test a Bit & Clear
        BCLR Dn,<ea>
        BCLR #<data>,<ea>
    BRA    Branch Always
        BRA <label>
    BSET    Test a Bit & Set

Page 250


     BSET Dn,<ea>
     BSET #<data>,<ea>
BTSTTest a Bit
     BTST Dn,<ea>
     BTST #<data>,<ea>
CHKCheck Register Against Bounds
     CHK <ea>,Dn
CLRClear an Operand
     CLR <ea>
CMPCompare
     CMP <ea>,Dn
     CMPA <ea>,An
     CMPI #<data>,<ea>
CMPMCompare Memory
     CMPM (Ay)+,(Ax)+
DBccTest Condition, Decrement, and Branch
     DBcc Dn,<Iabel>
DIVSSigned Divide
     DIVS <ea>,Dn Data
DIVUUnsigned Divide
     DIVU <ea>,Dn
EORExclusive OR Logical
     EOR Dn,<ea>
     EORI #<data>,<ea>
EXGExchange Registers
     EXG Rx,Ry
EXTSign Extend
     EXT Dn Data
ILLEGALIllegal Instruction
     ILLEGAL
impJump
     JMP <ea>
JSRJump to Subroutine
     JSR <ea>
LEALoad Effective Address
     LEA <ea>,An
LINKLink and Allocate
     LINK An,#<displacement>
LSLLogical Shift Left
     LSL Dx,Dy
     LSL #<daia>,Dy
     LSL <ea>
LSRLogical Shift Right
     LSP Dx,Dy
     LSR #<data>,Dy
     LSR <ea>
MOVEMove Data from Source to Destination
     MOVE <ea>,<ea>
     MOVEA <ea>,An
     MOVEO #<data>,Dn
MOVEMMove Multiple Registers
     MOVEM <register list>,<ea>
     MOVEM <eg&,<register llst>
MOVEPMove Paiipheral





     MOVEP DX' d A@,

                    7 6 x

               M VEP       d(A     '


MULS    Sipgngd    ult    I
    MULS    ea>    @D

MULUUnsigned Multiple
     MULTJ <ea>,Dn
NBCDNegate Decimal with Extend
     NBCD <ea>
NEGNegate
               NEG <ea>
          NEGX            Negate with Extend

Page 251


     NEGX <ea>
NOPNo Operation
     NOP
NOTLogical Complement
     NOT <ea>
OR lnclusive OR Logical
     OR <ea>, Dn
     OR Dn,<ea>
     ORI #<data>,<ea>
PEAPush Effective Address
     PEA <ea>
RESETReset External Device
     RESET
ROLRotate Left (without Extend)
     ROL Dx,Dy
     ROL #<data>,Dn
     ROL <ea>
RORRotate Right (without Extend)
     ROR Dx,Dy
     ROR #<data>, Dn
     ROR <ea>
ROXLRotate Left with Extend
     ROXL Dx,Dy
     ROXL #<data>,Dn
     ROXL <ea>
ROXRRotate Right with Extend
     ROXR Dx,Dy
     ROXR #<data>, Dn
     ROXR <ea>
RTEReturn from Exception
     RTE Data
RTRReturn and Restore Condition Codes
     RTR
RTSReturn from Subroutine
     RTS
SBCDSubtract Decimal with Extend
     SBCD Dy,Dx
     SBCD -(Ay),-(Ax)
SccSet according to Condition
     Scc <ea>
STOPLoad Status Register and Stop
     STOP #xxx
SUBSubtract Binary
     SUB <ea>,Dn
     SUB Dn,<ea>
     SUBA <ea>,An
     SUBI #<data>,<ea>
     SUBQ #<data>,<ea>
SUBXSubtract with Extend
     SUBX Dy,Dx
     SUBX -(Ay),-(Ax)
SWAPSwap Register Halves
     SWAP Dn
TASTest & Set an Operand
     TAS <ea>
TRAPTrap
     TRAP #<vector>
TRAPVTrap an Overflow
     TRAPV
TSTTest an Operand
     TST <ea>
UNLKUnlink
     UNLK An Data


Page 252

COMMAND INDEX

ACos            115        Borders            193        Cvi            117        Enable            194
AGABlue            165        Box            146        Cvl            117        End            100
AGAGreen        165        Boxf            146        Cvq            117        End            123
AGAPalRGB        165        Buffer            156        Cycle            166        End            95
AGARGB            165        ButtonGroup        189        CyclePalette        164        End            97
AGARed            165        Buttonid        193        End Function        99
ALibJsr            126        DCB            125        End Setint        100
AMIGA            121        CELSE            122        DEFTYPE            101        End Statement        98
ASLFileRequest$     202        CEND            122        Data            106        Endlf            96
ASLFontRequest        202        CERR:            123        Date$            119        Eof            110
ASLPathRequest$        202        CNIF            122        DateFormat        119        EraseMode        154
ASLScreenRequest    202        CSIF            122        Days            119        ErrFail            100
ASin            115        Call            127        DecodelLBM        145        Event            180
ASyncFade        166        Case            96        DecodeMedModule        172        EventCode        187
ATan            115        CaseSense        118        DecodePalette        164        EventQualifier        187
Abs            113        CatchDosErrs        111        DecodeShapes        152        EventWindow        180
Activate        184        Centre$            118        DecodeSound        170        Exchange        101
ActivateString        191        Chr$            116        Default            97        ExecVersion        120
AddFirst        102        Circle            146        DefaultlDCMP        178        Exists            111
AddlDCMP        179        Circlef            147        Defaultinput        107        Exp            115
Addltem            103        ClearList        102        DefaultOutput        107
AddLast            102        ClearRexxMsg        204        DeleteArgString        206        Fadeln            166
Addr            123        ClearString        191        DeleteMsgPort        203        FadeOut            166
AllocMem        128        ClickButton        211        DeleteRexxMsg        204        FadePalette        164
Asc            116        ClipBlit        158        Dim            102        FadeStatus        166
AsmExit            126        ClipBlitMode        158        Disable            194        False            113
AttachGTList        200        CloseEd            129        DiskBuffer        170        Fields            109
AutoCookie        150        CloseFile        109        DiskPlay        170        Filelnput        110
CloseScreen        174        DispHeight        113        FileOutput        110
BBlit            156        CloseSerial        214        Display            134        FileRequest$        107
BBlitMode        156        CloseWindow        186        DisplayAdjust        137        FileSeek        110
BLITZ            121        ClrErr            100        DisplayBitMap        136        FillRexxMsg        204
BLibJsr            126        Clrlnt            100        DisplayControls        137        Filter            170
Bank            128        Cls            146        DisplayDblScan        138        FindScreen        173
BankSize        128        CludgeBitMap        145        DisplayPalette        136        Firstitem        103
BeepScreen        174        ColSplit        133        DisplayRGB        138        FloatMode        106
Bin$            116        Colour            142        DisplayRainbow        138        FloodFill        147
BitMap            144        CookieMode        154        DisplayScroll        139        FlushBuffer        156
BitMapinput        143        CopLen            134        DisplaySprite        136        FlushEvents        180
BitMapOrigin        145        CopLoc            134        DisplayUser        139        FlushQueue        155
BitMapOutput        142        CopyBitMap        144        DoColl            161        For            97
BitMapWindow        145        CopyShape        150        DoFade            166        Forever            98
BitMaptoWindow        187        Cos            114        DosBuffLen        111        Format            105
BitPlanesBitMap        145        CreateArgString        206        DuplicatePalette    167        Frac            113
Blit            153        CreateDisplay        136        Frames            148
BlitColl        157        CreateMsgPort        203        EMouseX            184        Free            123
BlitMode        153        CreateRexxMsg        203        EMouseY            185        Free BitMap        144
BlitzKeys        140        CursX            142        EVEN            125        Free BlitzFont        142
BlitzQualifier        140        CursY            143        Edit            107        Free Module        170
BlitzRepeat        140        Cursor            182        Edit$            106        Free Palette        163
Block            157        CustomColors        138        EditExit        183        Free Window        177
BlockScroll        158        CustomCop        133        EditFrom        183        FreeBank        128
Blue            165        CustomSprites        138        Editat            182        FreeFill        147
BorderPens        193        CustomString        138        Else            96        FreeMacroKey        213
FreeMem            128        HTan            115        LoadPalette        163        OpenSerial        214
FreeSlices        133        Handle            150        LoadScreen        174
FromCLI            130        Hex$            116        LoadShape        149        PColl            162
Function        99        HideScreen        174        LoadShapes        149        PalRGB            164
Function Return        99        Hours            119        LoadSound        168        PaleneRange        167
LoadSprites        160        Par$            129
GTBevelBox        200        ILBMDepth        112        LoadTape        212        ParPath$        130
GTButton        198        ILBMHeight        112        Loc            111        Peek            113
GTChangeList        201        ILBMlnfo        112        Locate            142        Peek            127
GTCheckBox        198        ILBMViewMode        112        Lof            110        PeekSound        169
GTCycle            198        ILBMWidth        112        Log            115        Peeks$            127
GTDisable        201        INCBIN            122        Log10            115        PhoneticSpeak        172
GTEnable        201        INCDIR            122        LoopSound        169        PlayBack        212
GTGadPtr        200        INCLUDE            121        PlayMed            171
GTGetAttrs        201        If            96        MButtons        181        PlayModule        170
GTGetinteger        201        InFront            160        Macro            123        PlayWait        212
GTGetString        201        InFrontB        160        MacroKey        213        Plot            146
GTlnteger        199        InFrontF        160        MakeCookie        150        Point            146
GTListView        199        InitAnim        148        MaxLen            101        Pointer            140
GTMX            199        InitBank        128        Maximum            123        Poke            127
GTNumber        199        InitCopList        135        MenuChecked        197        Poly            147
GTPalette        199        InitPalette        164        MenuColour        197        Polyf            147
GTScroller        199        InitShape        152        MenuGap            196        PøP            98
GTSetAttrs        201        InitSound        169        MenuHit            180        Popinput        107
GTSetinteger        201        Inkey$            107        Menultem        195        Popitem            103
GTSetString        201        InnerCls        182        MenuState        197        PopOutput        107
GTShape            199        InnerHeight        185        MenuTitle        195        PositionSuperBitMap    186
GTSlider        199        InnerWidth        185        Menus            184        Previtem        103
GTStatus        201        Instr            116        Mid$            116        Print            105
GTString        199        Int            114        MidHandle        151        Processor        120
GTTags            200        InvMode            154        Mins            119        PropGadget        191
GTText            199        IsRexxMsg        210        Mki$            116        Pushitem        103
GTToggle        201        ItemHit            180        Mkl$            117        Put            110
GadgetBorder        193        ItemStackSize        104        Mkq$            117        PutReg            125
GadgetHit        180        Months            119        PutSuperBitMap        186
GadgetJam        190        Joyb            108        Mouse            140
GadgetPens        190        Joyr            108        MouseArea        141        QAMIGA            121
GadgetStatus        193        Joyx            107        MouseButton        211        QAbs            114
GameB            108        JoYY            108        MouseWait        98        QAngle            115
Get            110        JumpMed            171        MouseX            141        QBlit            155
GetMedinstr        172        MouseXSpeed        141        QBlitMode        155
GetMedNote        171        KillFile        111        MouseY            141        QFrac            114
GetMedVolume        171        Kililtem        103        MouseYSpeed        141        QLimit            114
GetReg            125        MoveScreen        175        QWrap            114
GetResultString        210        LCase$            118        Qualifier        181
GetRexxComrnand        209        LSet$            117        NEWTYPE            102        Queue            154
GetRexxResult()        209        Lastitem        103        NPrint            105        QuickPlay        212
GetSuperBitMap        186        Left$            115        NTSC            113        QuietTrap        213
GetaShape        150        Len            117        NewPaletteMode        163
GetaSprite        159        Let            101        Next            97        RGB Colour        164
Gosub            95        Line            146        NextFrame        148        RSet$            118
Goto            95        LoadAnim        148        Nextitem        103        RastPort        186
Green            164        LoadBank        128        NoCli            129        RawKey            181
LoadBitMap        145        NumDays            119        RawStatus        140

HCos            115        LoadBlikFont        141        NumPars            129        ReMap            147
HPropBody        192        LoadFont        187        Read            106
HPropPot        192        LoadMedModule        171        On            95        ReadFile        109
HSin            11.s    LoadModule            170        OpenFile        109        ReadMem            111
ReadSerial        214        SetMenu            196        Subitem            196        WMove            184
ReadSerialMem        215        SetPeriod        170        SubitemOff        196        WPlot            181
ReadSerialString    214        SetSerialBuffer        214        SysJsr            126        WPointer        184
Record            212        SetSerialLens        215        SystemDate        119        WPrintScroll        186
RectsHit        162        SetSerialParams        215        WScroll            182
Red            164        SetString        191        Tan            114        WSize            184
Redraw            192        SetVProp        192        TapeTrap        213        WTitle            186
RelMouse        210        SetVoice        172        TextGadget        189        WTopOff            186
Repeat            97        Sgn            114        Toggle            194        Wait            210
Replace$        116        ShapeGadget        190        TokeJsr            126        WaitEvent        179
ReplyRexxMsg        209        ShapeHeight        150        Translate$        172        WbToScreen        173
ResetList        102        Shapeltem        196        True            113        WeekDay            119
ResetString        191        ShapeSpriteHit        162        Type            211        Wend            96
Restore            106        ShapeSub        196         While            96
Return            95        ShapeWidth        150        UCase$            118        Window            176
RexxError()        210        ShapesBitMap        145        USED            123        WindowFont        183
RexxEvent        210        ShapesHit        162        USEPATH            121        WindowHeight        185
Right$            115        Shared            99        UStr$            118        Windowloput        178
Rnd            114        Show            133        UnBuffer        156        WindowOutput        178
Rotate            151        ShowB            133        UnLeft$            117        WindowTags        187
Runerrsoff        123        ShowBitMap        175        UnQueue            155        WindowWidth        185
Runerrson        123        ShowBlitz        134        UnRight$        117        WindowX            185
ShowF            133        Until            97        WindowY            185
SBlit            157        ShowPalette        163        Use            123        WriteFile        109
SBlitMode        157        ShowScreen        173        Use BitMap        144        WriteMem        111
SColl            162        ShowSprite        159        Use BlitzFont        142        WriteSerial        214
SMouseX            174        ShowStencil        157        Use Palette        163        WriteSerialMem        215
SMouseY            174        Sin            114        Use Slice        132        WriteSerialString    214
SaveBank        128        SizeLimits        186        Use Window        177
SaveBitmap        145        SizeOf            102        XFlip            151
SavePalette        164        Slice            131        VPos            113        XINCLUDE        122
SaveScreen        174        SolidMode        154        VPropBody        192        XStatus            212
SaveShape        149        Sort            104        VPropPot        192        YFlip            151
SaveShapes        149        SortDown        104        VWait            98
SaveSprites        160        SortList        104        Val            118        Years            119
SaveTape        212        SortUp            104        ViewPort        174
Scale            151        Sound            168        VoiceLoc        172
Screen            173        SoundData        169        Volume            169
ScreenPens        174        Speak            172
ScreenTags        175        SpriteMode        160        WBDepth            120
ScreensBitMap        144        SpritesHit        162        WBHeight        120
Scroll            147        Sqr            115        WBStartup        129
Secs            119        StartMedModule        171        WBViewMode        120
Select            96        Statement        98        WBWidth            120
SelectMode        190        Statement        98        WBlit            187
SendRexxCommand     206        Stencil            157        WBox            181
SerialEvent        215        Stop            96        WCircle            181
SetBPLCON0        134        StopCycle        166        WCls            182
SetColl            161        StopMed            171        WColour            183
SetCollHi        161        StopModule        170        WCursX            185
SetCollOdd        161        Str$            118        WCursY            185
SetCycle        165        String$            116        WEllipse        182
SetErr            100        StringGadget        190        WJam            183
SetGadgetStatus        189        StringText$        190        WLeftOff        186
SetHProp        192        StripLead$        117        WLine            182
Setlnt            99        StripTrail$        117        WLocate            185
SetMedMask        172        SubHit             180        WMouseX            184
SetMedVolume        171        SubiDCIP        179        WMouseY            184

Copyright

Copyright  1994  by  Acid Software,  a division of Armstrong  Communications
Limited,   New Zealand.  This document may not,  in whole or  in  part,   be
copied,  photocopied,  reproduced,  translaled, or reduced to any electronic
medium without prior consent, in writing, from Acid Software.

The  distribution and sale of this product are intended for the use  of  the
original  purchaser only.  Lawful users of this program are hereby  licensed
only  to read the program and its libraries from its medium into the  memory
of the computer solely for the purpose of executing the program.

Duplicating.  copying,  selling or otherwise distributing this product is  a
violation of the law.

Note:   Acid  Software  claim no intellectual or any  other  copyright  over
software developed in Blitz2 hy registered Blitz2 users.

Disclaimer

Acid  Sottware  accept no responsibility for the performance  of  Blitz2  or
software  developed with Blitz2.  However.  we wili endeavour to  solve  any
problems  registered users have with the product and  hope  to  support  the
product to the best of our ability.

Credits

Developed  hy  Mark  Sihly using HiSoft's Devpac2.  Printed  in  the  United
Kinydom  by  Guildhall Leisure Services ,Manual produced with  SoJt  Logik's
PageStream2 & PageLiner.

Technical Support

Users  are  not  entitled  to  any  support unless  reyistration  cards  are
re(urned.   Support  is  available  via email  from  [e-mail].   Acid
Software  can  also be contacted via fax in New Zealand on  +649  35X  165X.
Alternatively  mail  any  questions to  the  address  that  appeard  on  the
registration card enclosed in this pack.lge.

Upgrades

Blitz  BASIC  lor  lhe  Amica is continually heing  improved.   Updates  are
provided free by subscrihing to thc Blitz User Magazine (BUM),  details  are
included  on the registration card.  Sio:nificant additions to the  language
are  planned  for 1995 including Atari Jaguar support,  3D graphics  support
for troth Amiga and Jaguar. as well as a powerful new editor.

-- THE END --